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oc 


Describes the Occam 2 compiler. 


2 


occonf 


Describes the configurer which generates configuration 
binary files from configuration descriptions. 


3 


icoliect 


Describes the code collector which generates executable 
code files. 


4 


idebug 


Describes the network debugger. Lists the symbolic functions 
and Monitor page commands at machine level. 


5 


idump 


Describes the memory dumper tool which dumps root trans- 
puter memory for post mortem debugging. 


6 


iemit 


Describes the memory configurer tool which helps to confi- 
gure the transputer memory interface. 


7 


ieprom 


Describes the EPROM formatter tool which creates execut- 
able files for loading into ROM. 


8 


iiibr 


Describes the toolset librarian which creates libraries from 
compiled code files. 


9 


ilink 


Describes the toolset linker which links compiled code and 
libraries into a single unit. 


10 


Hist 


Describes the binary lister which displays binary files in a 
readable form. 


11 


imakef 


Describes the Makefile generator which creates Makefiles for 
toolset compilations. 


12 


imap 


Describes the map tool which generates a memory map for 
an executable file. 


13 


iserver 


Describes the host file server which loads programs onto 
transputer hardware and provides host communication. 


14 


isim 


Describes the transputer simulator which allows programs to 
be run without hardware. 


15 


iskip 


Describes the skip loader tool which loads programs onto 
external subnetworks. 
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Appendices 



A 


Toolset standards and 
conventions 


Describes the conventions and standards of the 
toolset. 


B 


Transputer types and 
classes 


Describes the meaning and use of transputer 
types and classes and lists the command line 
options to select them for the compiler and 
linker. 


C 


ISERVER Protocol 


Describes the server protocol and the 
ISERVER functions. 


D 


ITERM 


Describes the format of the ITERM files. 


E 


Bootstrap loaders 


Describes the INMOS bootstrap loading 
scheme and advises on how it might be custom- 
ized. 



72TDS367 01 



March 1993 



Contents 



Contents overview i 

Contents iii 

Preface xix 

Host versions xix 

About this manual xix 

About the toolset documentation set xx 

Other documents xxi 

FORTRAN toolset xxi 

INQUEST xxi 

Documentation conventions xxi 

Tools 1 

1 oc - occam 2 compiler ■ 3 

1.1 Introduction 3 

1 .2 Running the compiler 4 

1.3 Filenames 7 

1 .4 Transputer targets . , 

1 .5 Error modes 8 

1 .6 Enable/Disable Error Detection 8 

1 .7 Enabling/disabling warning messages 9 

1.8 Support for debugging 10 

1 .9 Separately compiled units and libraries 10 

1.10 Code insertion using ASM . . 11 

1.11 Memory map 11 

1.12 Compiler directives 12 

1.12.1 Syntax of compiler directives 13 

1.12.2 INCLUDE 13 

1.12.3 #USE 14 

1.12.4 #IMPORT 14 

1.12.5 #COMMENT 15 

1.12.6 #OPTION 16 

UNDEFINED error mode 17 

1.12.7 #PRAGMA 17 

#PRAGMA COMMENT "string* [comment] 18 



jv Contents 

#PRAGMA EXTERNAL "declaration" [comment] . . 18 

Examples: 18 

#PRAGMA LINKAGE [ M sectfon-name n ] [comment] . 18 
#PRAGMA TRANSLATE identifier "string" 

[ comment ] 20 

1.13 Error messages 20 

Notes 20 

1 .13.1 Warnings , 20 

1 .13.2 Errors 23 

2 occonf - occam configurer tool 27 

2.1 Introduction 27 

2.2 Running the configurer 28 

Examples of use: 28 

2.2.1 Search paths 30 

2.3 Boot-from-ROM options 30 

2.4 Configuration error modes 31 

2.5 Enable/Disable Error Detection 31 

2.6 Enabling memory re-ordering and placement 32 

2.7 Disabling virtual routing 32 

2.8 Enabling/disabling warning messages 32 

2.9 Support for interactive debugging 33 

2.10 ASM code , 34 

2.11 Support for INQUEST 34 

2.12 Default memory map 34 

2.12.1 LoadStart 35 

2.13 Configurer diagnostics 35 

2.13.1 Warning messages 36 

2.13.2 Error messages 38 

3 icollect — code collector 47 

3.1 Introduction 47 

Unconfigured program (using T option): 48 

Configured processor program: 48 

3.2 Running the code collector 48 

3.2.1 Examples of use 51 

3.2.2 Default command fine 51 

3.2.3 Input files 51 

3.2.4 Outputfiies 51 

Specifying an output filename 52 

Default case 52 

Boot-from-ROM/RAM 52 



Contents 



Dynamically loadable output 52 

Memory map files 52 

Debug data file 52 

3.3 Program interface for occam unconfigured programs 52 

3.3.1 Interface used for T option 53 

3.3.2 Interface used for T and l M' options 53 

3.4 Memory allocation for unconfigured programs 53 

3.4.1 C and FORTRAN programs 54 

3.4.2 occam programs 55 

3.4.3 Memory initialization errors 56 

3.4.4 Small values of IBOARDSIZE 56 

3.5 Parity-checked memory 57 

3.6 Non-bootable files created with the K option 58 

3.6.1 File format 58 

3.7 Boot-from-ROM output files 59 

3.8 Alternative bootstrap loaders for unconfigured programs — 60 

3.9 Alternative bootstrap schemes 60 

3.10 The memory map file - 60 

3.10.1 Unconfigured (single processor), boot from link ... 61 

Program targetted at transputer type 61 

Program targetted at transputer class 62 

3.10.2 Configured program bootfrom link 64 

3.10.3 Boot from ROM programs 65 

Unconfigured (single processor), bootfrom ROM, 

run in RAM 65 

Unconfigured (single processor), bootfrom ROM, 

run in ROM 65 

Configured program, bootfrom ROM, run in RAM . 65 

Configured program, bootfrom ROM, run in ROM . 65 

3.11 Disabling interactive debugging - Y option 66 

3.12 Error messages 67 

3.12.1 Warnings 67 

3.12.2 Serious errors 67 

3.12.3 Fatal errors 72 

idebug — network debugger 73 

4.1 Introduction - - 73 

4.2 Debugging the root transputer 73 

4.2.1 Board wiring 74 

4.2.2 Post-mortem debugging R-mode programs 74 

4.2.3 Post-mortem debugging T-mode programs 74 

4.2.4 Post-mortem debugging from a network dump file . 75 

4.2.5 Debugging a dummy network 75 

4.2.6 Methods for interactive breakpoint debugging 75 



Contents 

4.3 Running the debugger 75 

4.3.1 Toolset file types read by the debugger 77 

4.3.2 Environment variables 78 

4.3.3 Program termination 79 

4.4 Post-mortem mode Invocation 79 

4.4.1 Debugging T-mode programs - option T 80 

4.4.2 Debugging R-mode programs - option 'R' 80 

4.4.3 Debugging a network dump file - option 'N 1 80 

4.4.4 Debugging a previous breakpoint session - 

option W 81 

4.4.5 Re-invoking the debugger on single transputer 
programs 81 

44.6 Debugging boot from ROM programs 81 

4.5 Interactive mode invocation 81 

4.6 Function key mappings 82 

4.7 Debugging programs on INMOS boards 82 

4.7.1 Subsystem wiring 82 

4.7.2 Debugging options to use with specific board types 83 

4.7.3 Detecting the error flag in interactive mode 83 

4.8 Debugging programs on non-INMOS boards 84 

4.9 Monitor page commands 85 

4.9.1 Command format 85 

4.9.2 Specifying transputer addresses 85 

4.9.3 Scrolling the display 85 

4.9.4 Editing functions 86 

4.9.5 Commands mapped by [TERM 86 

4.9.6 Summary of commands 86 

4.9.7 Symbolic-type commands 88 

4.9.8 Scroll keys 88 

4.9.9 Monitor page command descriptions 89 

4.9.10 Symbolic-type commands 107 

4.10 Symbolic functions 108 

4.10.1 Symbolic functions 109 

4.10.2 Interactive mode functions 111 

4.10.3 Locating functions 112 

4.10.4 Cursor and display control functions 112 

4.10.5 Miscellaneous functions 113 

4.11 INSPECTyMODIFY expression language for C 115 

4.11.1 Syntax not supported 115 

4.11.2 Extensions to C syntax 115 

Subarrays 115 

Scope resolution operator 115 

Hex constants 116 

Address constant indirect 116 

4.11.3 Automatic expression pickup 116 



Contents vii 

4.11.4 Editing functions 117 

4.11.5 Warnings 117 

4.11.6 Types 118 

Type compatibility when using 118 

4.12 Display formats for source code symbols 119 

4.12.1 Notation 119 

4.12.2 Basic Types 120 

4.12.3 Default type of "plain" char 120 

4.12.4 Enumerated types 120 

4.12.5 Pointers 121 

4.12.6 Function Pointers 121 

4.12.7 Structs 121 

4.12.8 Unions 122 

4.12.9 Addressof operator & 122 

4.12.10 Arrays 122 

4.12.11 Channels 123 

4.13 Example displays 123 

4.14 INSPECT/MODIFY expression language for occam 125 

4.14.1 Inspecting memory 125 

4.14.2 Inspecting arrays 125 

4.14.3 Type compatibility when using 126 

4.15 Display formats for source code symbols 127 

4.15.1 Notation , 127 

4.15.2 Basic Types 127 

4.15.3 Channels 128 

4.15.4 Arrays 129 

4.15.5 Procedures and functions 129 

4.16 Example displays 129 

4.17 Error messages , 133 

4.17.1 Out of memory errors 133 

4.17.2 If the debugger hangs 133 

4.17.3 Error message list 133 

5 idump — memory dumper 143 

5.1 Introduction 143 

5.2 Running the memory dumper 143 

5.2.1 Example of use 144 

5.3 Error messages 144 

6 iemit — memory interface configurer 145 

6.1 Introduction 145 

6.2 Running iemit 146 

6.3 Output files , . 148 



viii Contents 

6.4 Interactive operation 148 

6.4.1 PageO 148 

6.4.2 Pagel 150 

6.4.3 Page 2 154 

6.4.4 Page 3 155 

6.4.5 Page 4 , 156 

6.4.6 Page 5 157 

6.4.7 Page 6 158 

6.5 iemit error and warning messages 159 

6.6 Memory configuration file 160 

7 ieprom - ROM program converter 163 

7.1 Introduction , 163 

7.2 Prerequisites to using the ieprom tool 164 

7.3 Running ieprom 164 

7.3.1 Examples of use 165 

7.4 ieprom control fite 165 

Statement 166 

Parameter/Description . . , 166 

Statement 168 

Parameter/Description . . 168 

7.5 What goes into the EPROM 168 

7.5.1 Memory configuration data 168 

7.5.2 Parity registers 169 

7.5.3 Jump instructions 169 

7.5.4 Bootable file 170 

7.5.5 Traceback information 170 

7.6 ieprom output files 170 

7.6.1 Binary output 170 

7.6.2 Hex dump 170 

7.6.3 Intel hex format 171 

7.6.4 Intel extended hex format 171 

7.6.5 Motorola S-record format 171 

7.7 Block mode 171 

7.7.1 Memory organization 171 

7.7.2 When to use block mode 172 

7.7.3 How to use block mode 172 

7.8 Example control files 173 

7.8.1 Simple output 173 

7.8.2 Using block mode 173 

7.9 Error and warning messages 174 

8 ilibr — librarian 175 

8.1 Introduction 175 



Contents ix 

8.2 Running the librarian 176 

Example 176 

8.2.1 Default command line 1 76 

8.2.2 Library indirect files 177 

8.2.3 Linked object input fifes 177 

8.2.4 Library files as input .... 177 

8.3 Library modules 177 

8.3.1 Selective loading 178 

8.3.2 How the librarian sorts the library index 178 

8.4 Library usage files 178 

8.5 Building libraries 179 

8.5.1 Rules for constructing libraries 179 

8.5.2 General hints for building libraries 179 

8.5.3 Optimizing libraries 179 

All libraries 180 

Libraries containing occam modules 180 

Semi-optimized library build targeted at all 

transputer types 180 

Optimized library targeted at all transputer types . . 181 

Library build targeted at specific transputer types . . 181 

8.6 Error Messages 1 82 

8.6.1 Warning messages 182 

8.6.2 Serious errors 182 

9 ilink — linker 185 

9.1 Introduction 185 

9.2 Running the linker 186 

9.2.1 Default command line 187 

9.3 Linker indirectfiles 187 

9.3.1 Linker indirectfiles supplied with the toolset 188 

9.4 Linker directives 188 

9.4.1 #aiias basename { aliases } 188 

9.4.2 #define symbolname value 189 

9.4.3 #include filename 189 

9.4.4 #mainentry symbolname 189 

9.4.5 Reference symbolname 189 

9.4.6 #section name 190 

9.5 Linker options 1 90 

9.5.1 Processor types 190 

9.5.2 Error modes - options H, S and X 191 

9.5.3 TCOFF and LFF output files - options T, LB, LC . . 191 

9.5.4 Extraction of library modules - option EX 192 

Example: Extraction from a user library 192 

Example: Extraction from a user library, using the 

run-time library 193 



Contents 



Example: Extraction from a user library, for 

multiple processor types 193 

Example: Generation of a completely linkable library 194 

Extraction using #define , 195 

9.5.5 Display information - option I 195 

9.5.6 Virtual memory - option KB 195 

9.5.7 Main entry point- option ME 195 

9.5.8 Link map filename - option MO 196 

9.5.9 Linked unit output file - O 196 

9.5.10 Permit unresolved references - option U 196 

9.5.11 Disable interactive debugging - Y 196 

9.6 Selective linking of library modules 196 

9.7 The link map file 197 

9.7.1 MODULE record: 197 

9.7.2 SECT record: 197 

9.7.3 MAP record: 198 

9.7.4 Value record: 1 98 

9.8 Using imakef for version control 198 

9.9 Error messages 199 

9.9.1 Warnings 199 

9.9.2 Errors 200 

9.9.3 Serious errors 201 

9.9.4 Embedded messages 203 

10 ilist - binary lister 205 

10.1 Introduction 205 

10.2 Data displays 205 

10.2.1 Modular displays 206 

10.2.2 Example displays used in this chapter 206 

10.3 Running the binary lister 206 

10.3.1 Options to use for specific file types 207 

10.3.2 Output device 208 

10.3.3 Default command line 208 

10.4 Specifying an output file - option O 208 

10.5 Symbol data - option A 209 

1 0.5.1 Specific section attributes 209 

10.5.2 General symbol attributes 209 

10.5.3 Example symbol data display 210 

10.6 Code listing - option C . . . . , 210 

10.6.1 Example code listing display 211 

107 Exported names - option E 212 

10.7.1 Example exported names display 212 

10.8 Hexadecimal/ASCII dump- option H 212 



Contents x[ 

10.8,1 Example hex dump display 213 

10.9 Module data - option M 213 

10.9.1 Example module data display 214 

10.10 Library index data - option N . . . . . , 214 

10.10.1 Example library index display 215 

10.11 Procedural interface data - option P 215 

10.11.1 Example procedural data display 215 

10.12 Specify reference - option R 216 

10.13 Full listing - option T 216 

10.13.1 Example full data display 216 

10.13.2 Configuration data files 217 

10.14 File identification - option W 217 

10.14.1 Example file identification display 218 

10.15 External reference data - option X 219 

10.15.1 Example external reference data display 219 

10.16 Error messages 219 

10.16.1 Warning messages 220 

10.16.2 Serious errors 220 

11 imakef — makefile generator 221 

11.1 Introduction 221 

11.2 How imakef works 221 

11 .3 File extensions for use with imakef 222 

11.3.1 Targetfiles 222 

1 1 .4 Linker indirect files 225 

1 1 .5 Library indirect and library usage files 225 

11.6 Running the makefile generator 225 

11.6.1 Example of use 227 

11.6.2 Specifying language mode 227 

11.6.3 Configuration description files 227 

11.6.4 Disabling debug data 228 

11.6.5 Removing intermediate files 228 

11.6.6 Files found on ISEARCH 228 

1 1 .6.7 Map file output for imap 228 

11.7 imakef examples 228 

11.7.1 C examples 229 

Singfe transputer program 229 

Multitransputer program 230 

11.7.2 occam examples 231 

Single transputer program 231 

Multitransputer program 232 

11.7.3 Mixed language program 233 

11.8 Format of makefifes 234 



xiv Contents 

14.4.1 Specifying numerical parameters 274 

14.4.2 Keys mapped by ITERM 274 

14.4.3 Command summary 275 

14.4.4 Command descriptions 275 

14.5 Batch mode operation 281 

14.5.1 Setting up ISIMBATCH 281 

14.5.2 Input command files 281 

14.5.3 Output 281 

14.5.4 Batch mode commands 281 

14.6 Error messages 282 

1 5 iskip - skip loader 285 

15.1 Introduction 285 

15.1 .1 Uses of the skip tool 285 

15.2 Running the skip loader 286 

1 5.2.1 Skipping a single transputer 287 

Subsystem wired down: 287 

Subsystem wired subs: 287 

15.2.2 Skipping multiple transputers 287 

1 5.2.3 Loading a program 288 

1 5.2.4 Monitoring the error status - option E 288 

15.2.5 Clearing the errorflag 289 

15.3 Error messages 289 

Appendices 291 

A Toolset conventions and defaults 293 

A.1 Command line syntax 293 

A.1 .1 General conventions 293 

A.1 .2 Standard options 293 

A.2 Unsupported options 294 

A.3 Filenames 294 

A.4 Search paths 294 

A.5 Standard file extensions 295 

A. 5.1 Main source and object files 296 

A.5.2 Indirect input files (script files) 297 

A.5. 3 Files read by the memory map tool imap 297 

A.5.4 Other output files 297 

A. 5.5 Miscellaneous files 298 

A,6 Extensions required for imakef , . 298 

A.7 Message handling 299 

A. 7.1 Message format 299 

A.7.2 Severities 299 



Contents xv 

A.7.3 Runtime errors 300 

B Transputer types and classes 301 

B.1 Transputer types supported by this toolset .... . 301 

B.2 Transputer types and classes 301 

B.2.1 Single transputer type 301 

B,2,2 Creating a program which can run on a range of 

transputers 302 

B.2,3 Linked file containing code compiled for different 

targets 303 

occam object files targetted at different targets .... 305 

B.2.4 Classes/instruction sets - additional information . . 305 

B.3 Transputer type command line options 307 

C iserver protocol 309 

C.1 iserver packets 309 

C.2 Server commands 309 

C.3 File commands . . 311 

C.3.1 Fopen - Open a file 311 

C.3.2 Fclose - Close a file 312 

C.3.3 Fread - Read a block of data 313 

C.3.4 Fwrite - Write a block of data 313 

C.3.5 FGetBlock - Read a block of data and return 

success 314 

C.3.6 FPutBlock - Write a block of data and return 

success . . . . 315 

C.3.7 Fgets - Read a line 315 

C.3.8 Fputs - Write a line 316 

C.3.9 Fflush - Flush a stream 316 

C.4 Record Structured file commands 317 

C.4.1 FopenRec - Open a record structured file 317 

C.4.2 FGetRec - Read a record 319 

C.4.3 FPutRec- Write a record 319 

C.4.4 FputEOF - Write an end of file record 320 

0.4.5 Fseek - Set position in a file 320 

C.4.6 Ftelf - Find out position in a file 321 

C.4.7 Feof- Test for end of file 321 

C.4.8 Ferrer - Get file error status 322 

C.4.9 Remove - Delete a file 322 

C.4.10 Rename - Rename a file 323 

C.4.11 Isatty - Discover if a stream is connected to a 

terminal 323 

CA12 FileExists- Check to see if a file exists 324 

C.4.13 FerrStat - Get file error status 324 

C.5 Host commands 325 



xvi Contents 



C.5.1 Getkey - Get a keystroke 325 

C.5.2 Pollkey - Test for a key 325 

C.5.3 RequestKey - Request a single keyboard 'event' . . 326 

C.5.4 Getenv - Get environment variable 326 

C.5.5 Time - Get the time of day 327 

C.5.6 System - Run a command 327 

C.5.7 Translate - Translate an environment variable 328 

C.6 Server commands 329 

C.6.1 Exit -Terminate the server 329 

C.6.2 CommandLine - Retrieve the server command line 329 

C.6.3 Core - Read peeked memory 330 

C.6.4 Version - Find out about the server 331 

C6.5 Getlnfo - Obtain information about the host and 

server 332 

C.6.6 CommandArgs - Retrieve the server command line 

arguments 333 

C.7 Reserved Tags and Third Party Tags 334 

C.7.1 MSDOS - Perform MS-DOS specific function 334 

C.7.2 SocketA - make a socket library call 335 

C.7.3 SocketM - make a socket library call 335 

C.7.4 ALSYS - Perform Alsys specific function 335 

C.7.5 KPAR - Perform Kpar specific function 336 

C.8 Record Structured file format 336 

C.8.1 SunOS and MS-DOS , , . . . 336 

Formatted Sequential 336 

Unformatted Sequential 336 

Formatted Direct , , 336 

Unformatted Direct 336 

C.9 Termination codes 337 

D ITERM files 339 

D.1 Introduction 339 

D.2 The structure of an ITERM file 339 

D + 3 The host definitions 340 

D.3.1 ITERM version 340 

D.3.2 Screen size , ,,.... 340 

D.4 The screen definitions 340 

D.4. 1 Goto X Y processing 341 

D.5 The keyboard definitions 342 

D.6 Setting up the ITERM environment variable 342 

D.7 Iterms supplied with a toolset 343 

D.8 An example ITERM 344 

E Bootstrap loaders 347 

E.1 Introduction 347 



Contents xvii 



E.1.1 The example bootstrap 347 

Transfer of control 348 

E.1.2 Writing bootstrap loaders 348 

Index 349 



xviii Contents 



Preface 



Host versions 

The documentation set which accompanies the Occam 2 toolset is designed to 
cover all host versions of the toolset: 

• IMS D7305 - IBM PC compatible running MS-DOS 

• IMS D4305 - Sun 4 systems running SunOS. 

• IMS D6305- VAX systems running VMS. 
About this manual 

This manual is the Toolset Reference Manual to the Occam 2 toolset. 

The manual provides reference material for each tool in the toolset describing: 

• Command line syntax, including an example command line, 

• Command line options. 

• How to run the tool. 

• A list of error messages which may be obtained. 

Many of the tools in the toolset are generic to other INMOS toolset products i.e. 
the ANSt C and FORTRAN toolsets and the documentation reflects this. Examples 
are given in C, 

The appendices provide details of: 

• Toolset conventions. 

• Transputer types. 

• Server protocol. 

• ITERM files. 

• Bootstrap loaders. 
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xx About the toolset documentation set 

About the toolset documentation set 

The documentation set comprises the following volumes: 

• 72 TDS 366 01 Occam 2 Toolset User Guide 

Describes the use of the toolset in developing programs for running on the 
transputer. The manual is divided into two sections; 'Basics' which 
describes each of the main stages of the development process and 
includes a 'Getting started" tutorial. The 'Advanced Techniques 1 section is 
aimed at more experienced users. The appendices contain a glossary of 
terms and a bibliography. Several of the chapters are generic to other 
INMOS toolsets. 

• 72 TDS 367 01 occam 2 Toolset Reference Manual (this manual) 

• 72 TDS 368 01 occarn 2 Toolset Language and Libraries Reference 
Manual 

Provides a language reference for the toolset and implementation data. A 
list of the library functions provided is followed by detailed information 
about each function. Details of extensions to the language are given in an 
appendix. 

• 72 TDS 37Q 00 Performance Improvement with the INMOS Dx305 Occam 
2 Toolset 

This document provides advice about how to maximize the performance 
of the toolset. It brings together information provided in other toolset docu- 
ments particularly from the Language and Libraries Reference Manual. 
Note: details of how to manipulate the software virtual through-routing 
mechanism are given in the User Guide. 

• 72 TDS 377 00 Occam 2 Toolset Handbook 

A separately bound reference manual which lists the command line 
options for each tool and the library functions. It is provided for quick refer- 
ence and summarizes information provided in more detail in the Tools 
Reference Manual and the Language and Libraries Reference Manual. 

• 72 TDS 378 00 Occam 2 Toolset Master Index 

A separately bound master index which covers the User Guide, Toolset 
Reference Manual, Language and Libraries Reference Manual and the 
Performance Improvement document. 
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Other documents 

Other documents provided with the toolset product include: 

• Delivery manual giving installation data, this document is host specific. 

• Release notes, common to all host versions of the toolset, 

• 'occam 2 Reference Manual' published by Prentice Hall. 

• '4 TutoriaUntroduction to Occam Programming' published by BSP Profes- 
sional Books. 

FORTRAN toolset 

At the time of writing the FORTRAN toolset product referred to in this document 
set is still under development and specific details relating to it are subject to 
change. 

INQUEST 

The INQUEST products referred to within this document are 1NMOS window- 
based debugging and profiling products, which may be bought separately and 
used with the toolset. 

Documentation conventions 

The following typographical conventions are used in this manual: 

Bold type Used to emphasize new or special terminology. 

Teletype Used to distinguish command line examples, code fragments, 
and program listings from normal text, 

Italic type In command syntax definitions, used to stand for an argument 

of a particular type. Used within text for emphasis and for book 
titles. 

Braces { } Used to denote optional items in command syntax. 

Brackets[] Used in command syntax to denote optional items on the 
command line. 

Ellipsis . . . Ingeneralterms.usedtodenotethecontinuationofaseries.For 
example, in syntax definitions denotes a list of one or more 
items. 

] In command syntax, separates two mutually exclusive alterna- 

tives. 
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1 oc - occam 2 

compiler 



This chapter describes the syntax and command line options of the Occam 2 
compiler oc. The chapter ends with a list of error messages. 

Appendix B of the Language and Libraries Reference Manual describes some 
technical aspects of Occam's implementation on the transputer, including the 
allocation of memory, the machine representation of Occam types, and other 
hardware dependencies. 

1.1 Introduction 

The toolset compiler implements the Occam 2 language targeting to IMS T212, 
M212, T222, T225, T400, T414, T425, T426, T800, T801, and T805 transputers. 
Transputer targets are discussed in detail in Appendix B. 

oc supports some extensions to the occam 2 language, including: compiler direc- 
tives; extended channel handling; extended syntax; and low level programming 
support. These are compiler-dependent and do not extend the definition of the 
language. Extensions supported by oc are listed in Appendix A of the Language 
and Libraries Reference Manual. 

Each compilation of a program must be targetted at a specific transputer type or 
class, in one of three execution error modes and with interactive debugging either 
enabled or disabled. The selection or not of interactive debugging determines the 
method of channel input/output used by the compiler 

All components of a program to be run on the same transputer must be compiled 
for compatible target processors, error modes, and method of channel i/o. The 
compiler provides comprehensive error message information. 

Libraries and separately compiled units must be already compiled before any file 
which references them can itself be compiled. It is the programmer's responsibility 
to ensure all components of a program are compiled in the correct order and that 
object code is kept up to date with changes in the source; the linker will object if 
this is not done. This may be assisted by using a MAKE program in conjunction with 
the imakef tool. The imakef tool depends on a particular system of file exten- 
sions being used. For details of version control using MAKE programs and the 
imakef tool see Chapter 11. The operation of the compiler in terms of standard 
file extensions is shown below. 

Occam source files can contain references to object code libraries, occam 
source to be included in the compilation, separately compiled Occam code, and 
code produced by compatible compilers for other languages. 
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For a full description and formal definition of the occam 2 language see the 
Occam 2 Reference Manual. 




The object file is generated by the compiler in Transputer Common Object file 
Format (TCOFF). Object files are required to be in this format to be compatible with 
other tools in the toolset such as the librarian and linker tools. 

1.2 Running the compiler 

The Occam 2 compiler takes as input an Occam source file and compiles it into 
a binary object file. Command line options determine the target transputer for the 
co mpilation, the compilation error mode, and other compiler facilities such as alias 
and usage checking. A target processor and compilation error mode should be 
specified for each compilation. The compiler default is to produce code for the T414 
in HALT mode, and for code of this type the transputer target and error mode 
options may be omitted. 

To invoke the compiler use the following command line: 
► oc filename {options} 

where: filename is the name of the file containing the source code. If you do not 
specify a file extension, the extension .occ is assumed. 

options is a list, in any order, of one or more of the options given in Table 
1.1. 



Options must be preceded by '- for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 



if no arguments are given on the command line a help page is displayed giving the 
command syntax. 
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If the compilation is unsuccessful, error messages are displayed giving the name 
of the file and the number of the line where the error occurred. Compiler error 
messages are listed in section 1.13. 

Example: 

UNIX based toolsets: 



oc -t425 simple 
ilink simple. tco hostio.lib 
occonf simple. pgm 
icollect simple. cfb 
iserver -se -sh simple. btl 



-t425 -f occama . Ink 



MS-DOS/VMS based toolsets: 

oc /t425 simple 

ilink simple. tco hostio.lib /t425 /£ occama. Ink 
occonf simple. pgm 
icollect simple. cfb 
iserver /se /sh simple. btl 

In this example the source code for a single processor program is compiled for a 
T425 transputer. The example also shows the commands for linking, configuring, 
collecting, and loading the program. 



Option 


Description 


Transputer 
type 


See Appendix B for transputer type options. 


A 


Prevents the compiler from performing alias checkingThis 
option also disables usage checking. The default is to perform 
alias checking. When alias checking is enabled, the compiler 
may insert run-time alias checks. Details of alias and usage 
checking rules are given in Appendix C of the Language and 
Libraries Reference Manual and also in the occam 2 Reference 
Manual. 


B 


Displays messages in brief (single Jine) format 


C 


Disables the generation of object code. The compiler performs 
syntax, semantic, alias and usage checking only 


code nnn 


Specifies how large to make the code buffer. If not specified, the 
compiler will allocate 240 Kbytes. The code buffer Is expressed 
as Kbytes, e.g. to allocate a buffer s 100kbytes, specify CODE 
100. 


D 


Generates minimal debugging information. The default is to 
produce full debugging information. Debugging data is required 
by the debugger and by the transputer simulator. 
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£ 


Disables the use of the compiler libraries. This prevents the 
compilation of some programs which require 'complicated' arith- 
metic such as real arithmetic on a processor which does not 
have a floating point unit. If this option is used and the occam 
code requires use of the libraries, an error is reported. 


6 


Enables the compiler to recognize the restricted range of trans- 
puter instructions via the ASM construct, as listed in section C.8 
of the User Guide. 


H 


Produces code in HALT mode. This is the default compilation 
mode and may be omitted for HALT mode programs. (See 
options s and X also). 


I 


Displays additional information as the compiler runs. This 
information includes target and error mode, and information 
about directives as they are processed. The default is not to 
display this information. 


K 


Disables run-time range checking. The default is to insert run- 
time range checks. See section 1.6, 


N 


Disables usage checking. The default is to perform usage 
checking. Usage checking is also disabled by option 'A'. Details 
of alias and usage checking rules are given in Appendix C of the 
Language and Libraries Reference Manual and also in the 
Occam 2 Reference Manual. 


NA 


Disables the insertion of run-time checks for calls to assert. 


NWCA 


Disables warnings when CHAN OF ANY is used. See section 
1.7. 


NWGY 


Disables warnings when the obsolete construct guy is used. 
See section 1 .7. 


NWP 


Disables warnings when function or procedure parameters are 
not used. See section 1 .7. 


NWU 


Disables warnings when declared variables or routines are not 
used. See section 1.7. 


o outputftie 


Specifies the name of the output file. If no output file is specified 
the compiler uses the current directory and input filename and 
adds a .tco extension. 


P filename 


Generates a map file giving details of code mapping in memory. 
A filename must be specified. Map files can be displayed as 

normal text files and are read by the imap tool. See section 1.11 


R filename 


Redirects error messages to a file. 


S 


Produces code in STOP mode. (See options h and x also). 


U 


Disables the insertion of code to perform run-time error checks. 
The default is to perform run-time error checks. See section 1 .6. 


v 


Prevents the compiler from producing code which has a sepa- 
rate vector space requirement. The default is to produce code 
which uses separate vector space. See section B.1.4 in the 
Language and Libraries Reference Manual, 
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w 


Enables the compiler to recognize the full range of transputer 
instructions via the asm construct. Transputer instructions are 
listed in Appendix C of the User Guide. 


WALL 


Enable all warnings which are controlled from the com mand line . 
See section 1.7. 


WD 


Provides a warning whenever a name is descoped. See section 
1.7. 


WO 


Provides a warning whenever a run-time aEias check is gener- 
ated. See section 1.7. 


WQUAL 


Enables software quality warnings, see section 1.7. 


X 


Produces code in UNIVERSAL mode. See section 1.5. (See 
options H and S also). 


Y 


Disables interactive debugging. See section 1,8. Note: This 
option also disables the Virtual routing' facilities of the confi- 
gurer. 



Table 1.1 occam 2 compiler options 

1.3 Filenames 

occam source files can be given any legal filename for the host system you are 
using. The use of the .occ extension for occam source, and the . inc extension 
for files containing declarations of constants and protocols, is recommended. If an 
extension is not specified for the input file, the compiler will assume the extension 
is .occ. 

Output files are specified using the '0' option. If you do not specify a filename, the 
input filename is used (minus any directory name) and a . tco file extension is 
added. In this case the file will be placed in the current directory i.e. the directory 
from which the compiler is invoked. 

If you use the Makefile generator tool imakef you must use the extensions 
described in section 11.3. 



1 .4 Transputer targets 

The compiler produces code for the IMS T212, M212, T222, T225, T400, T414, 
T425, T426, T800, T801, and T805 transputers. Command line options are 
provided to specify the processor type for the compilation. If more than one 
processor type is specified, the compilation will terminate immediately and an error 
message wilf be displayed. If no target is specified the compilation defaults to a 
T414 target. 

Programs may also be targetted at transputer classes, which enable the same 
code to be run on groups of related transputer types. 

A description of transputer types and classes can be found in Appendix B. 
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1.5 Error modes 

The execution error mode determines the behavior of a program if it fails during 
execution. There are two main modes; HALT system and STOP process. There 
is also a special mode called UNIVERSAL. Command line options are provided to 
select the error mode for the compilation. Specifying more than one error mode will 
cause the compilation to terminate immediately and an error message will be 
displayed. 

The execution behavior of programs compiled in the different modes is as follows: 

HAL T When an error occurs in the program the transputer halts. This 

is useful for developing and debugging systems and is the 
default mode. For errors to be detected correctly the server must 
be invoked with the 'SE' option. 

STOP When an error occurs the system behaves like the Occam 

STOP process, that is the process causing an error does not 
continue. Other processes continue until they become depen- 
dent upon the stopped process. This ensures that a failure in 
one process does not automatically produce failure in other 
processes. Using this mode it is possible to build a system with 
redundancy and enable a system to run even if parts of the 
program fail or processes fail because a time out is exceeded. 

UNIVERSAL UNIVERSAL mode enables the user to compile code that may 
be run with either HALT or STOP mode in effect. The decision 
about which mode to adopt need not be taken until the sepa- 
rately compiled modules are combined into a linked object file. 
On linking the modules, any code that has been compiled in 
UNIVERSAL error mode will adopt the error mode of the other 
modules i.e. either HALT mode or STOP mode. HALT and 
STOP error modes may not be combined on the same 
processor. 

Code compiled in either HALT or STOP mode may call code compiled in 
UNIVERSAL mode, however, code compiled in UNIVERSAL mode may only call 
code which has also been compiled in UNIVERSAL mode. It cannot ca[| code 
which has been compiled in HALT or STOP mode. 

All separately compiled units for a single processor must be compiled for compat- 
ible error modes. Where a library is used the module with the appropriate error 
mode will be selected. 

Compilation error modes and their effects are described in more detail in section 
5.3 of the occam 2 Toolset User Guide. 

1.6 Enable/Disable Error Detection 

By default the compiler inserts code to execute run-time checks for errors it cannot 
detect at compile time. In some circumstances it may be desirable to omit the run 
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time error checking in one part of a program, for example, in a time-critical section 
of code, while retaining error checks in other parts of a program, for debugging 
purposes. Three command line options are provided to enable the user to control 
the degree of run-time error detection performed; they are the 'k\ 'U' and 'NA 1 
options. 

The compiler option 'K' disables the run-time range checks for the module being 
compiled. Range checking only includes checks on array subscripting and array 
lengths. 

The compiler option 'u' prevents the compiler from inserting any code to explicitly 
perform run-time checks. This will disable run-time checks associated with type 
conversion, shift operations, array access, range validation and replicated 
constructs such as SEQ, par, if, and alt. Runtime checks implicit in the trans- 
puter instructions are still performed, for example, add will automatically check for 
arithmetic overflow. 

Note; The 'u' option can be used to remove unnecessary runtime checks from 
code which is fully debugged and known to be error-free. It is equivalent to 
implementing the Occam error mode UNDEFINED. 

The ( NA' option prevents the compiler from inserting any code to check calls to 
ASSERT, In effect, each ASSERT behaves tike SKIP. Any calls to ASSERT which can 
be evaluated at compile time will still be checked. 

The effect of using these options is described in detail in section 5.3.2 of the 
occam 2 Toolset User Guide. 



1.7 Enabling/disabling warning messages 

There are several command line options which allow the user to either enable or 
disable the generation of certain warning messages produced by the compiler: 

• The NWCA option disables the generation of warning messages when CHAN 
OF ANY is used. CHAN OF ANY is now considered obsolete and replace- 
ment with named protocols of type ANY is recommended. See section A.2.3 
of the occam 2 Toolset User Guide. 

• The NWGY option disables the generation of warning messages when the 
guy construct is used, guy is now considered obsolete and asm should be 
used instead. 

• The nwp option disables warning messages being generated when param- 
eters to procedures are not used. 

• The nwu option disables warning messages being generated when vari- 
ables or routines are not used. 

• The WALL option turns on all warnings which are controlled from the 
command line i.e. it is currently equivalent to WD, WO and wqual. 
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• The wd option provides a warning whenever a name is descoped, for 
example when a name is used twice and one occurrence of it is hidden 
within an inner procedure. See section 8 of the OCCBfT) 2 Reference 
Manual for details of Occam scope rules. 

• The wo option provides a warning whenever a run-time alias check is 
generated i.e. to check that variables do not overlap. These checks 
generate extra code and the user may wish to be alerted to this. 

• The wqual option enables software quality warnings. Currently these 
include a warning about incorrect positioning of PLACE statements and a 
warning about unused CASE options. 

Section 1.13.1 lists the warning messages which are affected by these options. 

1 .8 Support for debugging 

The Occam 2 compiler supports interactive debugging with idebug by default. 
When interactive debugging is enabled the compiler will generate calls to library 
routines to perform channel input and output, rather than using the transputer's 
instructions. 

Interactive debugging may be disabled using the compiler 'Y 1 option. This option 
forces the compiler to use sequences of transputer instructions for channel input 
and output, resulting in faster code execution. Note: This option also disables the 
'virtual routing' facilities of the configurer. 

Code which has interactive debugging disabled may call code which has interac- 
tive debugging enabled, but not vice versa. However, when interactive debugging 
is disabled in one part of the program this will prevent the interactive features of 
the debugger being used on the program as a whole. 

The compiler 'D' option disables the generation of full debugging data. Minimal 
debugging data remains to allow the debugger to backtrace through the code. This 
option enables library code to be created without the overhead of debugging data. 

1.9 Separately compiled units and libraries 

Any group of one or more Occam procedures and/or functions may be compiled 
separately provided they are completely self-contained and make no external 
references except via their parameters or compiler directives. Separate compila- 
tion is used to reduce the need for recompilation, and to split compilations into 
smaller parts. Separately compiled code is known as a compilation unit. 

Any collection of compilation units may be made into a library using the librarian 
ilibr (see chapter 8). Libraries and compilation units differ in the following way: 

• Libraries are selectively loaded as required by the transputer type and error 
mode of the compilation, whereas separately compiled units are always 
loaded. If a unit containing incompatible code is used an error is generated, 
whereas libraries containing incompatible code are ignored. 
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All separate compilation units and libraries must be compiled before the program 
that references them is itself compiled. An easy way to ensure this is to use the 
toolset Makefile generator imafcef with a suitable Make utility. For more details 
see Chapter 11. 

1.10 Code insertion using ASM 

Two compiler options are provided to enable the compiler to recognize transputer 
instructions inserted into source code using the ASM construct. The 'G' option 
permits use of a limited range of sequential instructions whereas the *w' option 
permits use of the full range of transputer instructions. For further details see 
Appendix D of the User Guide, Transputer instructions are listed in Appendix C of 
the User Guide. 

1.11 Memory map 

The compiler may be instructed, via the P mapftle option, to produce a map of work- 
space for each function defined in the file. The file contains information which may 
assist the user during program debugging. The map is written to the file mapftle. 

The file consists of a series of workspace maps, one for each routine, giving details 
of workspace requirements. These are followed by a section map listing details of 
procedures and functions. 

/ N 

Map of code and data for source file simple. occ 

Created by occam 2 compiler Beta Vn 2,01,79 (19:33:49 Oct 20 1992) {SunOS-S 
un4) 

Target processor : T4 
Error mode : HALT 



Map of workspace 






Routine : simple 




Variable name 


Offset 


(words } 


SanonO 




4 


length 




5 


result 




€ 


buffer 




10 


Formal parameter name 


Offset 


(words) 


fs 




s 


ts 




9 


memory 




10 


<hidden dimension> 




11 


<vector3pace_pointer> 




12 



Workspace size = 53 words, Vectorspace size =128 words 
Section map 



Section name : text%base : size = 164 bytes 

Name Type Offset (bytes) 

simple code 3 

Figure 1.1 Example compiler map 
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The file is generated in text format. The following information is present: 

• The name of the source file for which the map of code and data is being 
produced. The full pathname will be given if it exists. 

• Version data for the compiler 

• The target transputer of the compilation, T805, T400, etc. 

• The error mode of the compilation. 

• Nameoftheroutineforwhichthemapofworkspace is being produced. Items 
in the workspace map are given in ascending order of workspace offset. 

• List of local variables giving their offset (in words) into the routine's work- 
space. This list may include temporary variables introduced by the 
compiler. 

• List of formal parameters giving their name and offset (in words) into the 
routine's workspace. Parameters added by the compiler may also be 
listed, see Table 1.2. 

• The workspace and vector space requirements of the routine in words. 
This includes the requirements of all nested calls but not the four word 
overhead introduced by the transputer call instruction. 

• Name of the section for which the section map is being produced. Items in 
the section map are given in ascending order of section offset. 

Details of how the compiler allocates space for variables are given in section B.1 
of the Language and Libraries Reference Manual. 



Formal parameter 



hidden dimension 



vectorspace pointer 



static link 



Table 1 .2 Parameters inserted by compiler 

Note: The message "No local variables" may be displayed if no user vari- 
ables are found, however, compilertemporaries may have been assigned to work- 
space. In addition some compilertemporaries may not be listed in the map file. 

Information generated in the compiler map file may be extracted by the imap tool 
This toof can be used to produce a memory map for the program after it has been 
compiled, linked and collected. See chapter 12. 

1 .12 Compiler directives 

The Occam compiler supports a number of directives that allow the programmer 
to customize a compilation. All are extensions to the language. If the compiler T 
option is used directives are displayed on the screen as the compilation proceeds. 
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Directives supported are: 

#incldde - inserts occam source code 

#use - references separately compiled units and libraries 

#IMP0RT - references non-occarn compiled code 

#comment - inserts comments in object code 

#OPTlON - allows selection of compiler options from within source text 

#FRAGMA - miscellaneous extensions, including supportforthe Import of 
other languages, code placement in RAM, and disablement 
of checks on specific variables. 

1.12.1 Syntax of compiler directives 

Filenames referred to in compiler directives must be enclosed in double quotes ("). 
Files are located according to the search strategy defined in section A.4 of the 
Tools Reference Manual. 

If double quotes are to be used within a directive, the double quote character must 
be preceded by an asterisk (*), 

The scope of directives are defined, like declarations of constants and protocols, 
by the level of indentation in the occam source. 

When imakef is used, if a filename in a #USE, # INCLUDE or #IMPORT directive 
does not already have an extension then imakef will add the appropriate exten- 
sion depending upon the target that it is attempting to build. If you use the Makefile 
generator tool imakef you must use the extensions described in sections 1 1 ,3 and 
A. 6 of the Tools Reference Manual 

1.12.2 #INCL0TJE 

The #include directive inserts the contents of a named file at the point in the 
program source where the directive occurs, with the same indentation as the direc- 
tive. 

#INCLUDE files can be used by any number of programs, including separately 
compiled units, and are commonly used to share common declarations of 
constants and protocols between several programs. 

To track file dependencies within included files use of the imakef tool is recom- 
mended. 

The syntax of the # include directive is as follows: 

#INCLUDE "filename" [comment] 

where: filename is the name of the file to be included. The extension must be 
supplied. 

comment is any text preceded by the characters ' — '. 
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The first text afterthe directive must be the filename enclosed within double quotes 
("). All other text on the line Is ignored and may be used for comments. For 
example; 

#INCLUDE "header. inc" 

Included files may be nested to any depth. 

1.12.3 #USE 

The #USE directive allows separately compiled Occam units and libraries (in 
TCOFF format) to be referenced from Occam source. The file referenced by the 
#USE directive must be compiled for a compatible processor type and compilation 
mode as the main program, and should be made available in all modes for which 
the program will be compiled. 

The compiler ignores all library modules compiled with a processor type or 
compilation mode incompatible with the current compilation. A library may be used 
in any number of separately compiled units or other libraries, provided that each 
unit contains the #use directive. 

Any names in the library which do not conform to Occam syntax, and which have 
not been translated by means of a TRANSLATE pragma will be ignored. Note: this 
means that a TRANSLATE pragma must precede its related #USE directive. See 
section 1.12.7. 

The syntax of the #USE directive is as follows: 

#USE "filename" [comment] 

where: filename is the name of the object code file. The object file can be a 
compiled {. tco) or library (.lib) file. If you omit the file extension, the 
compiler adds the extension of the outputfile. This will be . tco unless you 
specified an output filename using the ( 0' option. 

comment is any text preceded by the characters [ — '. 

The firsttext afterthe #USE directive must be the filename, which must be enclosed 
within double quotes ("). Ail other text on the line Is ignored and may be used for 
comments. For example: 

#USE "module " 
#USE "library. lib" 
#USE "module. tco" 
#USE " module. t2h" 

1.12.4 #IMPORT 

The #import directive allows code produced by compatible non-occam 
compilers to be referenced from Occam programs. It operates in the same way 
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as #USE except that the code that is imported is marked as foreign' and not 
included in makefile searches. 

Note: The code imported by # IMPORT must be compatible with the current toolset 
linker ilinJc. 

The syntax of the # import directive is as follows: 

#IMP0RT "filename" [comment] 

where: filename is the name of the compiled equivalent occam process. If no 
extension is given the .tco extension is assumed. 

comment is any text preceded by the characters ' — '. 

The first text after the #imp0RT directive must be the file name, which must be 
enclosed within double quotes ("). All other text on the line is ignored and may be 
used for comments. 

An example of how to use the # IMPORT directive is given below: 

#IMPORT "centry.lib" — C interface code 



PROC . ENTRY £ fs , ts, flag, wsl, ws2, in, out) 
— call C language program 

The parameters supplied in the program call, flag, wsl, ws2, in, and out are 
those of the type 2 procedural interface. The program must be linked with C 
libraries centry . lib and libc. lib. Details of this method of mixed language 
programming can be found in section 11 .2 of the User Guide, 

Details of an alternative method of mixed language programming where non- 
occam programs are called directly using library functions can also be found in 
Chapter 11 of the User Guide. 

1.12.5 #COMMENT 

The #COMMENT directive allows comments to be placed in the object code. These 
comments can be read by the binary lister tool ilist. 

The syntax of the #COMMENT directive is as follows: 

#COMMENT "string" [comment] 

where: string is the text of the comment. Comments must be enclosed in double 
quotes following the #COMMENT directive. Comments cannot be split over 
more than one line. 
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Comments may not appear at the exact position in the object code corresponding 
with the source code directive, but the sequence of comments in the file is always 
maintained. Comments included by #comment are stripped from the object code 
when ft is linked or made bootable. 

The main use for the #comment d irective is in libraries or other pre-compiled code 
where it can be used to indicate a version number, record dependencies on other 
libraries, and hold copyright information. The comment strings can then be 
displayed using ilist. 

An example of how to use the #COMMENT directive is given below: 

PROC my. lib {) 

#COMMENT "My library VI, 3 , 18 May 1988" 
#COMMENT "Copyright me 1988" 

SEQ 

. . - library source 

#comment acts like # pragma comment. For example: 

#comment "string" 

is equivalent to: 

#PRAGMA COMMENT "String" 

See also section 1.12.7. 

1.12.6 #OPTION 

The #option directive allows you to specify certain command line options within 
the source text of a compilation unit, so that they apply only to that unit. Options 
specified in this way are simply added to the command line when the compiler is 
invoked. 

Arguments to #option are those that relate directly to the source, namely: 

A - disable alias (and usage) checking. 

E - disable the compiler libraries. 

G - allow sequential code inserts (via the ASM construct), 

K - disable the insertion of run-time range checks. 

N - disable usage checking. 

U - disable the insertion of any run-time error checks. 

V - disable separate vector space usage. 

W - enable full code inserts, (via the ASM construct). 

Y- disable interactive debugging. 

Specifying any other option produces an error. Descriptions of the arguments can 
be found in Table 1.1. 
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#0PTI0N directives can only appear in the file to which they apply; they cannot be 
nested in an included file. #OPTlON directives must also be the first non-blank or 
non-comment text in the source file. If they are found at any other position in the 
file an error is reported. 

The syntax of the #OPTlON directive is as follows: 

#Option "optionname {optionname}" [comment] 

where: optionname is any option permitted in a #OPTlON directive. Spaces within 
the double quotes are ignored. No option prefix character is required in the 
syntax and none should be specified. 

comment is any text preceded by the characters ' — '. 

The first text after the #OPTlON directive must be the list of options enclosed in 
double quotes. All other text on the line is ignored and may be used for comments. 

An example of how to use the #option directive is given below. In the example 
the unit does not require usage checking but contains transputer code inserts from 
the restricted set. 

— This compilation unit requires sequential 

— code inserts and does not pass the usage check. 

#OPTION "G N" 

PROC X {) 

body of procedure 

The #OPTlON directive should only be used for compiler options that are always 
required for a specific compilation. 

UNDEFINED error mode 

#option "U" can be used to implement the occam error mode UNDEFINED. 

1.12.7 #PRAOiA 

The fPRAGMA directive is provided to reference segments of code for mixed 
language compilations and/or finking functions: 

#pragma pragma-name {optional values] [comment] 

where: pragma-name may be one of: 

COMMENT 

EXTERNAL 

LINKAGE 

PERMITALIASES 

SHARED 

TRANSLATE 
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optional values may be specified for each type of pragma. The values that 
the options may take are specific to the pragma being used; they are 
described below. 

comment is any text preceded by the characters ' — \ AH pragma types may 
have a comment appended to them. 

#pragma COMMENT "string" [comment] 

#pragma COMMENT allows comments to be placed in the object code. These 
comments can be read by the binary lister tool ilist. In all respects #pragma 
comment acts like #COmment (see section 1.12.5). 

#pragma external "declaration" [comment] 

This directive allows access to other language compilations, declaration is a PROC 
or FUNCTION declaration, with formal parameters which correspond to the 
required calling convention. This is followed (within the string) by two numbers in 
decimal, indicating the number of workspace slots (words) and optionally the 
number of vectorspace slots to reserve for that call. The number of vectorspace 
slots defaults to 0. The number of the workspace slots should not include those 
needed to set up the parameters for the call. Note: that if the vectorspace require- 
ment is zero, then no vectorspace pointer parameter will be passed to the routine. 

It is important to ensure that enough space is allocated, both for workspace and 
vectorspace, because the compiler cannot check for overruns. 

The syntax of the declaration is as follows: 

formal procedure or function declaration - workspace [, vectorspace] 

Examples: 

#PRAGMA EXTERNAL "PROC pi {VAL INT x, y) = 20" 

#PRAGMA EXTERNAL "PROC p2 (VAL INT x, y) = 20, 100" 

#PRAGMA EXTERNAL "INT FUNCTION fl (VAL INT x, y) = 50" 

#PRAGMA EXTERNAL "INT FUNCTION f2 (VAL INT x, y) =50, 0" 

The procedure or function name is the name by which the external routine is 
accessed from the occam source. It is also the name which will be used by the 
linker to access the external languagefunction, though this may be modified by use 
of the translate pragma. 

#pragma LINKAGE ["section-name"] [comment] 

This pragma enables the user to identify modules that he wishes to be placed in 
on-chip RAM. The user may then prioritize the order in which these modules are 
linked together by using a linker directive. On-chip RAM is allocated to workspace 
first and then to code. Provided there is enough RAM available it should be 
possible for commonly used subroutines to be processed in the on-chip RAM. This 
should make the program run faster. 
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Normally the compile: creates the object code in a section named "text%base ] \ 
The #pragma likkage directive causes the compiler to change the name of the 
section to that supplied in the string. If the directive is used but no section name 
is provided by the user, the compiler supplies the priority section name 
"pri%text%base". More than one module may take the section name 
,f pri%text%base'\ 

A linker directive is used to change the order in which code modules are linked 
together, by supplying a list of prioritized section-names, see section 9.4.6. 
Provided that the linker does not encounter any linker directives listing section- 
names, it will place "pri%text%base" modules first. Any unnamed modules are 
added in an undefined order at the end of the linked unit 

Note: floating point routines such as REAL320P and REAL320PERR are automati- 
cally optimized by the compiler by placing them in a "pri%text%base" section. 

The #PRAGMA LINKAGE directive should appear at the start of the source code, 
immediately following the #OPTlON directive, if one is present. 

For example: 

#OPTIOK "N" 

#PRAGMA LINKAGE "PRIORITY!" - highest priority 

# PRAGMA PERMITALIASES variable Mst [comment] 

This pragma disables alias checking for specified variables. It may be applied to 
normal variables, abbreviations and RETYPES, or non-VAL formal parameters. 

See Appendix C in the Language and Libraries Reference Manualiora description 
of alias checking. 

This pragma must immediately followthe declaration of the variable it refers to, e.g. 

int x, y, z : 

PRAGMA PERMITALIASES x 

PRAGMA PERMITALIASES y is correct 

int x : 

int y : 

PRAGMA PERMITALIASES x is incorrect 

#PRAGMA SHARED variable Jist [comment] 

This pragma disables usage checking for specified variables. It may be applied to 
normal variables, abbreviations and RETYPES, or non-VAL formal parameters. 

See Appendix C in the Language and Libraries Reference Manuallo: a description 
of usage checking. 

This pragma must immediately follow the declaration of the variable it refers to, in 
the same manner as the pragma PERMITALIASES, see above. 
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^PRAGMA translate identifier "string" [ comment ] 

This Is used to enable linkage with routines whose entry point names do not corre- 
spond to Occam syntax for identifier names; both imported names to be called by 
this compilation unit and exported names defined in this compilation unit. An entry 
point is a name which is visible to the linker. Thus procedures and functions 
declared at the outermost level of a compilation unit are entry points, whereas 
nested procedures and functions are not. 

Any entry point defined in the compilation unit whose name matches identifier is 
translated to string when inserted into the object file, and hence can only be refer- 
enced as string when linking. String may not contain the NUL character {'*#00'). 

Any entry points in fuSEd libraries and other compilation units whose names 
match string can be referred to within the compilation unit as identifier. This also 
applies to identifiers defined by external pragmas, translate pragmas must 
precede any reference to their identifier. 

For example: 

# PRAGMA TRANSLATE c. routine "coroutine" 
#PRAGMA EXTERNAL "PROC c. routine () = 100" 

1.13 Error messages 

All messages produced by the compiler are in the standard toolset format. Details 
of the format can be found in section A,7. Messages are generated at severity 
levels Information, Warning, Error, and Fatal. No messages are generated at 
severity level Serious. 

No object files are generated if an error occurs. 

Notes 

1 The compiler libraries are automatically loaded if required, unless the 
compiler 'E' option is used. 

2 The compiler finds the compiler libraries by searching the path specified by 
the host environment variable isearch. The most common cause of a 
compiler library error is failure to set up this logical name correctly. 

The error messages listed here are those which are produced by incorrect use of 
the compiler, caused for instance by failing to specify command line options 
correctly. The compiler also reports afl syntax and semantic errors found in the 
program; these messages are not listed here as they are language specific and 
therefore outside the scope of this document. 

1.13.1 Warnings 

Badly formed #PRAGMA name directive 

The pragma directive does not conform to the required syntax. 
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CHAN OF ANY is obsolete: use PROTOCOL name IS ANY 

The CHAN OF ANY construct is now considered obsolete. The ability to 
define a named protocol as in protocol name is any provides greater 
security and should be used in preference. This warning may be disabled 
by means of the kwca command line switch. 

GUY construct is obsolete: use ASM instead 

The GCY construct is obsolete; the asm construct provides greater security 
and should be used in preference. This warning message may be disabled 
by means of the NWGY command line switch. 

name is not used 

The named variable is never used. This warning may be disabled by the 
Nwu command line option. 

Name name descopes a previous declaration 

This name descopes another name which has already been declared. This 
warning is only enabled when the WD command line option is used. 

No compatible entrypoints found in name 

The named library contains no routines which may be called from this error 
mode and/or processor type. 

Obsolete channel type conversion: use channel RETYPE 

The ability to pass a CHAN OF any as an actual parameter to a procedure 
whose formal parameter is a different channel type is obsolete. A channel 
retype should be inserted before the call to make the type conversion 
explicit. This warning may be disabled by means of theNWCA command line 
switch. 

Parameter name is not used 

The named parameter is never used. This warning may be disabled by the 
NWP command line option. 

Placement expression for name clashes with virtual routing system 

The named variable is placed on one of the transputer links. This may inter- 
fere with the INMOS interactive debugging system or the virtual routing 
system. 

Placement expression for name wraps around memory 

The calculation of the machine address for this variable has overflowed; 
the truncated address is used. 
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PLACEment must immediately follow declaration of name 

There should be no other variable declarations between a variable's own 
declaration and any modifying piace statement. This warning is enabled 
for place statements by the WQual command line switch. 

Possible side-effect: PLACED variable name 

A PiACEd variable has been declared inside a valor The com piler can not 
ensure that this cannot cause a side-effect. 

Possible side-effect: instanced PROC has PLACED variable name 

A PLACEd variable has been declared inside a PROC which is called from 
within a valof. The compiler cannot ensure that this cannot cause a side- 
effect. 

PORT name must be placed 

A port type must be placed using an allocation. See the Occam 2 Refer- 
ence Manual for further details. 

Routine name is not used 

The named routine was never called. This warning may be disabled by the 
NWU command line option. 

Run-time disjointness check inserted 

number Run-time disjointness check inserted 

The compiler has inserted run-time checks to ensure that variables are not 
aliased (i.e. that they do not overlap). This warning is only enabled when 
the wo command line option is used. 

TRANSLATE ignored: Module containing name has already been loaded 

The ^translate pragma must precede any #USE of a library containing 
that string. 

TRANSLATE ignored: Name name has already been used 

You may not specify multiple translation strings for the same name. 

TRANSLATE ignored: String contains NUL character 

The specified string for a #translate pragma may not include a NUL 

(zero) byte. 

TRANSLATE ignored: String name has already been used 

You may not specify multiple names to be translated to the same string. 
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Unknown #fragma name: name 

The pragma name is ignored. 

Using length 'name' in array part of counted array input is obsolete 

The language no longer permits using the length part of a counted array 
input to appear in the array part It does however allow the following special 
case to be written where the length only appears as the length of a slice: 

channeLexp ? name : : [ array.exp from for name ] 

This is transformed by the compiler into the equivalent construct: 

channeLexp ? name : : array.exp 

The former construct Is obsolescent and programs should be re-written to 
use the latter form. 

Workspace clashes with variable placed at workspace number 

A variable has been placed at the workspace address number, and this 
clashes either with another placed variable, or with the compiler's work- 
space allocation requirements. 

1.13.2 Errors 

Bad object file format 

Library or separately compiled procedure object code is not in the correct 
format. The code may not have been linked correctly, or the file may have 
become corrupted. 

Badly formed compiler directive 

A compiler directive following # was not recognized. 

Badly formed #EXTERNAL directive 

The number of workspace slots to reserve for the call has not been speci- 
fied or negative workspace or vector space slots have been specified in 
error. 

Cannot open file "string" 

File is missing, or file system error. 

Cannot open output file 

The object file could not be opened. File system error. 
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Cannot open output file {string) 

The file given as parameter to the command line R option could not be 

opened. 

Cannot open source file 

The source file cannot be opened. Either it does not exist, or there is a file 
system error. 

Code buffer full (nnn bytes); use command line to increase buffer size 

The compiler has an internal bufferfor code which is about to be placed into 
the object file; this has overflowed. The CODE command line option may be 
used to increase the size of this buffer. 

Code insertion is not enabled 

You must use the G or w options to enable assembler inserts. 

Descriptor has incorrect format 

Library or separately compiled procedure object code is not in the correct 
format. The code may not have been linked correctly, or the file may have 
become corrupted. 

Duplicate error modes on command line 

Multiple error modes may not be specified for the compilation. 

Duplicate processor types on command line 

Multiple processor types may not be specified for the compilation. 
Expected string after #COMMENT 

#COMMENT directive must be followed by a string containing the comment. 
Expected string after #OPTION 

#OPTiON directive must be followed by a string containing the options . 

'Filename 1 is not a valid object file 

Library or separately complied unit object code is not in the correct format. 
The code may not have been linked correctly, or the file may have become 
corrupted. 

Instruction is not available in current code Insertion mode 

You must set the w option in order to use this instruction. 
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Instruction is not available on target processor 

The given instruction is not present in the target instruction set. 
Invalid command line option [string] 

The user specified an unrecognized command line option. 
Missing filename 

Filename is missing on #USE, #INCLUDE or #IMP0RT directive. 
Missing object file name 

There is no object file name parameter to the command line option. 
Missing output file name 

There is no output file name parameter to the command line R option. 
No filename given 

No source file was specified on the command line. 

number reading source file 

File system error. The source file or an include file could not be read. 
number Is the host file system error number. 

number writing to object file 

File system error. The object file could not be written to. number is the host 
file system error number. 

Option in illegal position 

Only one #0PTI0N directive is allowed in a file, and it must be on the first 
non-blank or non-comment line in a file. 

PRAGMA must immediately follow declaration of name 

There should be no other variable declarations between a variable's own 
declaration and any modifying # PRAGMA. 

Run out of symbol space 

The source compilation unit is too large to be compiled. 
Unrecognised option "char" in option string 

incorrect compiler options specified after a #Option directive. 
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2 occonf - occam 

configurer 

This chapter describes the configurer tool occonf that configures code for trans- 
puter networks. It describes the command line syntax and explains how the tool 
Is used to generate a configuration data file for input to the code collector tool. The 
chapter ends with a list of error messages. 

2.1 Introduction 

The configurer takes a configuration description created using the transputer 
configuration language and produces a configuration data file which icollect 
uses to generate bootable code for a transputer network. The bootable code may 
be generated in a specific error mode. 

A configuration description describes how code is to be run on a network of trans- 
puters. It consists of separate definitions of the software and hardware networks, 
and a mapping description which defines how the software will be placed on the 
processor network. Using this description the configurer allocates code to partic- 
ular processors and performs wide ranging consistency checks on the mapping 
of software to hardware. Chapter 6 in the User Guide explains how to write a 
configuration description. 

Linked modules and libraries which are referred to by a configuration description 
must be already compiled and linked before any file which references them can 
itself be configured. 

The operation of the configurer tool is illustrated below. Files are represented in 
terms of their standard toolset file extensions. 




occonf produces two output files: 

• the main configuration data file (. cfb) for the collector 

• a file ( . clu) containing executable code packets, used by the collector. 
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2.2 Running the configurer 

To run the configurer use the following command line: 

► occonf Filename {options} 

where: filename is the configuration description file. If no file extension is specified, 
the extension .pgm is assumed. Only one file may be specified. 

options is a list of one or more options from Table 2.1 . 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upperor lower case and can be given in any 
order. 

Options must be separated by spaces. 



If no arguments are given on the command line a help page Is displayed giving the 
command syntax. 

Examples of use: 

UNIX based toolsets: 

oc simple 

ilink simple. tco hostio.lib -f occama.lnk 

occonf simple. pgm 

icollect simple, cfb 

iserver -sb simple. btl -se 

MS-DOS and VMS based toolsets: 

oc simple 

ilink simple, tco hostio.lib /f occama.lnk 

occonf simple. pgm 

icollect simple. cfb 

iserver /sb simple* btl /se 
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Option 


Description 


B 


Displays messages in brief (single line) format. 


C 


Disables the generation of object code. The configurer performs 
syntax, semantic, alias and usage checking only. 


CODE nnn 


Specifies how large to make the code buffer, if not specified, the 
configurer will allocate 40 Kbytes, nnn is a value in Kbytes i.e. the 
"K 1 suffix is not required. 


6 


Enables the configurerto recognize the restricted range of trans- 
puter instructions, via the ASM construct. See section 2.10 and 
Appendix C in the User Guide. 


GA 


Generates a configuration which can be debugged using the 
/WQ(JES7~debugger. This option is incompatible with the RA, RO, 
w, y, pre and eru options. 


H 


Produces code in HALT error mode. This is the default configura- 
tion mode and may be omitted for HALT error mode programs. 
See section 2.4. 


I 


Displays extra information as the tool runs. This information 
indudes target and error mode, and information about directives 
as they are processed. The default is not to display this informa- 
tion. 


K 


Disables run-time range checking. The default is to insert run- 
time range checking. See section 2.5, 


NA 


Disables the insertion of run-time checks for calls to assert. 
See section 2.5. 


NV 


Disables the 'virtual routing' capabilities. If this option is speci- 
fied, then processors may only communicate with adjacent 
processors, and no more than 1 channel in either direction may 
use any transputer link. See section 2.7. 


NWCA 


Disables warnings when CHAN OF ANY is used. See section 
2.8. 


NWGY 


Disables warnings when the obsolete construct guy is used. See 
section 2,8. 


NWP 


Do not warn if declared parameters are not used. 


NWU 


Do not warn if declared variables or routines are not used. 


o outputffle 


Specifies an output filename. If no output file is specified the 
configurer uses the input filename and adds the extension , cfb. 


PRE 


Generates a configuration which can be profiled using the 
INQUEST network execution profiler. Note: This option cannot 
be used with the ga, ra, ro or PRO options. 


PRU 


Generates a configuration which can be profiled using the 
INQUEST network utilization profiler. Note; This option cannot 
be used with the GA, ra, RO or PRE options. 


r filename 


Redirects error and information messages to a file. 
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2.3 Boot-from-ROM options 



RA 


Creates a file suitable for a boot-from-ROM application in which 
the code and data are both loaded into RAM. interactive debug- 
ging must be disabled using the Y option. 


RE 


Enables re-ordering of code and data layout in memory, using 
the order . code, order . vs and order .ws attributes. 
Also enables the location . code, location . ws, and loca- 
tion. vs attributes. See section 2.6, This option disables the 
ability to use idebug but not the INQUEST debugger. 


RO 


Creates a file suitable for a boot-from-ROM application in which 
the code is loaded into ROM and the data is loaded into RAM. 
Interactive debugging must be disabled using the y option. 


S 


Produces code in STOP error mode. See section 2.4. 


U 


Disables the insertion of all extra run-time erTor checking. The 
default is to insert run-time error checks. This is a 'stronger' 
option than K, and can be used to implement the Occam UNDE- 
FINED error mode. See section 2,5, 


V 


Prevents the configurer from producing code which has a sepa- 
rate vector space requirement. The default is to produce code 
which does use separate vector space. 


H 


Enables the configurer to recognize the full range of transputer 
instructions, via the asm construct. See section 2.10 and 
Appendix C in the User Guide. 


WALL 


Enable all warnings, See section 2.8. 


WD 


Provides a warning whenever a name is descoped. 


WO 


Provides a warning whenever a run-time alias check is gener- 
ated. 


WQUAL 


Enables software quality warnings, see section 2,8, 


X 


Produces code En UNIVERSAL error mode. See section 2.4. 


Y 


Disables interactive debugging with idebug. See section 2.9. 



Table 2.1 occonf command line options 



2.2.1 Search paths 

If a directory path is not specified the configurer uses the standard toolset search 
mechanism for locating input files, include files, and system library files. Briefly, the 
current directory is searched first, followed by the directories specified by 
ISEARCH (if defined on the system). For details see section A4, 



2.3 Boot-from-ROM options 

The boot-from-ROM options 'RO' and 'RA.' indicate that the program is to be 
collected for loading into EPROM and select the execution mode (from ROM or 
RAM) for the root transputer code. Interactive debugging must be disabled. 
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2.4 Configuration error modes 

The configuration error mode determines the behavior of a program if it fails during 
execution. The execution behavior of programs configured in the different modes 
is as follows: 



HALT 


An error halts the transputer immediately. 


STOP 


An error stops the process and causes graceful degradation. 


UNIVERSAL 


Code configured in this mode behave as either HALT or STOP 
mode, according to the state of the transputer's HaltOnError 
flag. 



The error mode selected for the configuration must be compatible with the error 
mode of the compiled units, referenced by the configuration source. The confi- 
gurer will produce an error message, if this is not the case. 

Table 2.2 indicates the compilation error modes which are compatible and the 
possible error mode they may be configured for. 



Compatible compilation error modes 


occonf options 


HALT, UNIVERSAL 


H 


STOP, UNIVERSAL 


s 


UNIVERSAL 


X 



Table 2.2 occonf error modes 

Compilation error modes and their effects are described in more detail in section 
5.3.1 Note: that occam UNDEFINED mode can be achieved by using the confi- 
gurer 'U' option, to disable the insertion of run-time checks. This option behaves 
in the same way as the 'u' option to the occam compiler, which is documented in 
section 5.3.2 of the User Guide. 



2.5 Enable/Disable Error Detection 

By default the configurer inserts code to execute nun-time checks for errors it 
cannot detect during configuration. In some circumstances it may be desirable to 
omit the run-time error checking in one part of a program, for example, in a time- 
critical section of code, while retaining error checks in other parts of a program, for 
debugging purposes. Three command line options are provided to enable the user 
to control the degree of run-time error detection performed; they are the *K\ 'u' and 
'na 5 options. 

The 'K' option disables the insertion of run-time range checks on array subscripting 
and array lengths. 

The 'U' option prevents the configurer from inserting any code to explicitly perform 
run-time checks. This option will disable run-time checks associated with type 
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conversion, shift operations, array access, range validation and replicated 
constructs such as SEQ, par, if, and alt. 

The l NA' option prevents the configurer from inserting any code to check calls to 
assert. In effect, each assert behaves like skip. Any calls to assert which can 
be evaluated during configuration will still be checked. 

Note: that some checks are still performed; some transputer instructions implicitly 
check for erroneous conditions. 

The K, D and NA options behave in exactly the same way, as the same options 
provided for the Occam compiler. The effects of using these options are described 
in section 5.3.2 of the User Guide. 

2.6 Enabling memory re-ordering and placement 

The 'RE' option enables the user to have more control of the layout of code and 
data areas in memory. When this option is used, the special processor attributes 
'order . code', 'order .vs' and 'order . ws f which indicate the relative priority of 
different data areas, and the placement attributes location .code, loca- 
tion, ws, and location. vs, are enabled. See sections 6.5.5 and 6.5.7 in the 
User Guide for more details. 

Note: use of this option means that idebug cannot be used, neither in interactive 
mode nor in postmortem mode. 

2.7 Disabling virtual routing 

The virtual routing facilities of the configurer are normally enabled, that is, the 
configurer automatically adds virtual routing and multiplexing processes if they are 
required by the configuration, and any explicit placements are ignored. 

If virtual routing is not required the virtual router can be disabled by using the W 
command line option. In the absence of explicitly supplied multiplexing processes, 
the normal limit of two channels per link (one in each direction) and a maximum 
of 4 links applies. If these limits are exceeded and no multiplexing is provided the 
configuration will not compile. Note: the use of the W option also has an effect 
on the value of LoadStart, see section 2.12.1. 

Note: The 'NV 1 option can be used to reproduce the channel behavior of the 
D7205/D5205/D6205 Occam 2 toolsets, if this is required. 

Note: if any part of the program has been compiled with interactive debugging 
disabled this will also disable the use of virtual routing. 

2.8 Enabling/disabling warning messages 

There are several command line options which allow the user to either enable or 
disable the generation of certain warning messages by the configurer: 
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• TheNWCAoptiondisablesthegenerationofwaming messages when CHAN 
OF ANY is used. CHAN OF any is now considered obsolete and replace- 
ment with named protocols of type any is recommended. See section 
A.2.3 of the Occam 2 Toolset Language and Libraries Reference Manual. 

• The NWGY option disables the generation of warning messages when the 
GUY construct is used, guy is now considered obsolete and asm should be 
used instead. 

• The NWP option disables warning messages being generated when param- 
eters to procedures are declared and not used. 

• The nwu option disables warning messages being generated when vari- 
ables or routines are not used, 

• The wall option turns on all warnings i.e. it is currently equivalent to wd, 
wo and wqual. 

• The wd option provides a warning whenever a name is descoped, for 
example when a name is used twice and one occurrence of it is hidden 
within an inner procedure. See section 8 of the Occam 2 Reference 
Manualfor details of occam scope rules. 

• The WO option provides a warning whenever a run-time alias check is 
generated i.e. to check that variables do not overlap. These checks 
generate extra code and the user may wish to be alerted to this. 

• The WQUAL option enables software quality warnings Currently these 
include warnings for unused options in case inputs and warnings about 
badly positioned PLACE statements. 

Section 2.13.1 lists the various warning messages which are affected by these 
options. 

2,9 Support for interactive debugging 

Interactive debugging with idebug is supported by default. When interactive 
debugging is enabled the configurer will generate calls to library routines to 
perform channel input and output, rather than using the transputer's instructions. 
Interactive debugging must be enabled in order to use the Interactive features of 
the debugger. 

Note: when interactive debugging and virtual routing are both enabled, the direct 
placement of channels on inter-processor links is ignored by the configurer. See 
section 6.5.2 of the Occam 2 Toolset User Guide for more details. 

Interactive debugging may be disabled by using the configurer f Y' option. If this 
option is used in conjunction with the W option the configurer is forced to use 
sequences of transputer instructions for channel input and output, resulting in 
faster code execution. 
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Code which has interactive debugging disabled may call code which has interac- 
tive debugging enabled, but not vice versa. However, when interactive debugging 
is disabled in one part of the program this will prevent the interactive features of 
the debugger being used on the program as a whole and will also prevent the use 
of virtual routing (see section 2.7). 



2.10 ASM code 

Two configurer options are provided to enable the configurer to recognize trans- 
puter instructions, via the asm construct (see Appendix D of the User Guide). 

The 'W option enables the full range of transputer instructions, as listed in 
Appendix C of the User Guide. The 'G' option enables the use of a limited range 
of sequential instructions, as listed in section C.8 of the same appendix. Examples 
of the use of transputer code insertion can be found in Chapter 13 of the User 

Guide. 

The transputer instruction set is documented in full in the Transputer Instruction 
Set - A compiler Writer's Guide. 



2.11 Support for INQUEST 

The ga, pre and pru command line options support the use of the INMOS 
INQUEST debugging and profiler tools. 



2.12 Default memory map 

By default the configurer maps code into memory into the same order as the 
compiler i.e. beginning at Load Start; workspace; code; separate vector space. 
The memory segments are contiguous. The upper limit of the memory available 
to the configurer is defined in the configuration description file ( .pgm file), by the 
memsize attribute specified for the processor node. The default memory map is 
illustrated in Figure 2.1. 
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Figure 2.1 occonf default memory map 

Thefirst2or4 Kbytes of memory above mostheg int is implemented ason-chip 
RAM, and includes a few words which are reserved by the transputer hardware 
for the implementation of links and other hardware registers, LoadStart is either 
just above or coincident with MemStart, see below. Free memory is unused 
memory, not available to the program. 

2.12.1 LoadStart 

The position of LoadStart for a processor varies depending on the use of occonf 
command line options and the reserved processor attribute, optionally specified 
within a configuration description. 

When the reserved processor attribute is specified, LoadStart is defined to be 
the memory location obtained by adding the value of reserved to MOSTNEG int. 

When the reserved processor attribute is not specified, LoadStart is coincident 
with or just above MemStart: 

• LoadStart = (MOSTNEG [NT + 40 words) when no command line options 
are used i.e. virtual routing support is enabled. 

• LoadStart = (MemStart + 6 words) when the W command line option is 
specified, disabling virtual routing, but debugging or profiling is enabled 
either for idebug or the INQUEST product. 

• LoadStart = MemStart when the W command line option is specified but 
neither idebug or the INQUEST debugger or profiler are used. 

The value of LoadStart can be checked once the application has been collected, 
by generating and examining the collector map file. 

2.1 3 Configurer diagnostics 

If the source code does not conform to the Occam 2 configuration language defini- 
tion, then the configurer will issue diagnostics, in the form of error messages, 
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during the compilation process. When this occurs no object file nor configuration 
binary file will be produced. 

Errors in the configuration source produce diagnostic messages in standard 
toolset format. Details of the format can be found in section A.7. 

Diagnostics are generated at the standard severity levels information, Warning, 
Error, and Fatal, No messages are generated at severity level Serious, 

Warning messages are listed below. 

2.13.1 Warning messages 

In the following list the Warning prefix is omitted for clarity. 

Badly formed #PRAGMA name directive 

The pragma directive named does not conform to the required syntax. 

CHAN OF ANY is obsolete: use PROTOCOL name IS ANY 

The CHAN OF ANY construct is now considered obsolete. The ability to 
define a named protocol as in protocol name is ANY provides greater 
security and should be used in preference. This warning may be disabled 
by means of the nwca command line switch. 

GUY construct is obsolete: use ASM instead 

The GUY construct is obsolete; the ASM construct provides greater security 
and should be used in preference. This warning message may be disabled 
by means of the nwgy command fine switch. 

Exceeded linkquota on processor name, n Inputs, n Outputs 

The configurer needs to use more links than permitted by the linkquota 
attribute to route the channels for this program. The linkquota attribute 
will be ignored. 

name is not used 

The named variable is never used. This warning may be disabled by 
means of the NWO command line option. 

Name name descopes a previous declaration. 

This name descopes another name which has already been declared. This 
warning is only enabled by means of the WD command line option. 

No channel has been placed onto the host connection 

place or map statements should be used to define channel input/output 
across the host connection, if host communication is required. 
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No direction known for channel name on PROCESSOR name 

The configurer cannot determine whether channel name is used for input 
or output on this processor it will make a guess. 

Obsolete channel type conversion: use channel RETYPE 

The ability to pass a CHAN OF ANY as an actual parameter to a procedure 
whose formal parameter is a different channel type is obsolete. A channel 
retype should be inserted before the call to make the type conversion 
explicit. This warning may be disabled by means of the nwca command line 
switch. 

Parameter name is not used 

The named parameter is never used. This warning may be disabled by 
means of the NWP command line option. 

Placement expression for name clashes with virtual routing system 

The named variable is placed on one of the transputer links. This may Inter- 
fere with the INMOS interactive debugging system or the virtual routing 
system. 

Placement expression for name wraps around memory 

The calculation of the machine address for this variable has overflowed; 
the truncated address is used. 

Placement of name is ignored because interactive debugging is enabled 

A channel placement on an ARC has been ignored. This is because the 
debugger idebug, which is enabled by default, requires all channel 
connections between processors to be implemented as virtual channels. 

Possible side-effect: PLACED variable name 

A PLACEd variable has been declared inside a valof. The compiler cannot 
ensure that this cannot cause a side-effect. 

Possible side-effect: instanced PROC has PLACED variable name 

A PLACEd variable has been declared inside a PROC which is called from 
within a VALOF. The compiler cannot ensure that this cannot cause a side- 
effect. 

Processor name unused 

The named processor has no code placed onto it. 

Routine name is not used 

The named routine is never called. This warning may be disabled by 
means of the nwj command line option. 
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Run-time disjointness check inserted 
number Run-time disjointness checks inserted 

The configurer has inserted run-time checks to ensure that variables are 
not aliased (i.e. that they do not overlap). This warning is only enabled by 
means of the WO command line option. 

Unknown #PRAGMA name: name 

The named pragma is unknown and therefore ignored. 
Using length 'name' in array part of counted array input is obsolete 

The language no longer permits using the length part of a counted anay 
input to appear in the array part. It does however allow the following special 
case to be written where the length only appears as the length of a slice: 

channeiexp ? name : : [ array.exp FROM FOR name ] 

This is transformed by the compiler into the equivalent construct: 

channeiexp ? name : : array.exp 

The former construct is obsolescent and programs should be re-written to 
use the latter form. 

Workspace clashes with variable placed at workspace number 

A variable has been placed at the address number \n workspace, and this 
clashes either with another placed variable, or with the configurer's work- 
space allocation requirements. 

2.1 3.2 Error messages 

Most of the messages in this section have been caused by mis-use of the configu- 
ration language. Forfurther help see chapters 6, 1 and appendix A of the occem 
2 Toolset User Guide. These messages are generated at the severity level Error. 

name has already been mapped 

name appears twice on the left-hand side of a map or place statement 

name has already been used as a physical NODE 

Some attributes have already been set for name, so it can only be used as 
a physical node and not as a logical node. 

ARC name has already been connected 

Examine all 'CONNECT' statements creating link connections between 
processor edges or a processor edge and an external edge. 
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Attribute name has already been set on NODE name 

Check the declaration of node name and any attributes defined for name 
in the mapping and network sections. 

Attribute name has not been set for NODE name 

Attribute name is a mandatory node attribute and should be set in the 
NETWORK description. 

Attribute name may not be SET 

You may not set a link attribute. 

Attribute name may not be used on logical NODEs 

Logical nodes cannot have attributes set for them. Perhaps you meant to 
set the attribute for a node representing a physical processor. 

Attribute name set to illegal value on NODE name 

Check the syntax and range of permitted values for the type of attribute 
required. For further help see the relevant chapters of the User Guide as 
indicated at the start of this section. 

CHAN name is placed but not properly connected 

Check that the ARC that CHAN name is PLACEd on is connected within the 
NETWORK description by a CONNECT statement. 

CONNECT expression must be of type EDGE 

CONNECT expressions connect two nodes or a node to an external edge 
by specifying their link connections. They take the form: 

'connect edge TO edge [with arcname] ' 

where arcname is optional. 
Cannot PLACE name which was declared outside a PROCESSOR construct 

PLACE statement must immediately follow channel declaration. 

Cannot disable interactive debugging with the INQUEST debugger 

You have used both of the command line options 'Y' and *GA'; they are 
incompatible. 

Cannot disable virtual routing with the INQUEST debugger 

You have used both of the command line options W and 'GA'; they are 
incompatible. 
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Cannot interactively debug ROM programs 

If you are configuring for boot-from-ROM i.e. you have used either the ra 
or RO command line options, you must disable interactive debugging by 
using the Y option. 

If you want to debug your program, develop it as a boot-from-link program 
and debug, and when it is clear of errors re-configure for boot-from-ROM. 

Cannot run both profilers together 

You have used both the PRE and pru command line options, selecting both 
INQUEST profiler tools. These tools are mutually exclusive. 

Cannot run the profiler on ROM programs 

The PRE or pru command line options have been used in conjunction with 
the ra or RO command line options. 

Cannot run the profiler with the INQUEST debugger 

The pre or PRU command line options have been used in conjunction with 
the GA command line option. 

Cannot set NODE name as root; another has already been set 

Examine the other processor declarations, one of them has the root 
attribute set 

Cannot use VAL on a CHAN, PORT, TIMER, or hardware item 

Abbreviations of CHAN, PORT, TIMER, node, ARC and EDGE cannot use 

VAL'. 

Cannot use VAL on a hardware item 

It is illegal to use VAL on a NODE, ARC or edge. 

Channel name is mapped onto ARC name, not connected to this processor 

You need to identify which physical or logical processor is connected to 
ARC name. Either the ARC is connected to the wrong processor or you are 
trying to map the wrong channel to ARC name. 

Channel name is used for both input and output, but ARC name connects to 
an EDGE 

ARC name connects this processor to an edge, so this processor can input 
on it or output on it but cannot do both. Two channels are required to 
support two-way communication. 

Channel name mapped onto unconnected ARC name 

arc name is required to be connected to a physical link. This is done using 
a CONNECT statement within the network description e.g.: 

'CONNECT edge TO edge [WITH arcname] ' 
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Channel name used for input by more than one process 

Channel name appears in a previous processor statement, defining a 
process and its channels. 

Channel name used for output by more than one process 

Channel name appears in a previous PROCESSOR statement, defining a 
process and its channels. 

Channel name with protocol containing INT used across different word- 
lengths 

This is a constraint of the current configurer, see section A.7 of the Occam 
2 Toolset User Guide. 

Code buffer full {nnn bytes); use command line to increase buffer size 

The configurer has an internal buffer for code which is about to be placed 
into the object file; this has overflowed. The code command line option 
may be used to increase the size of this buffer 

EDGE name has already been connected 

Edge name has been connected in a previous CONNECT statement. 

EDGE name is not connected to rest of network 

Edge name defines a peripheral device which, if it is to be used, needs to 
be connected to the rest of the network by a connect statement. 

Expected a NODE attribute, found a subscript expression 

You appear to have used too many subscripts. The configurer expected to 
see the name "link" as in: 

connect name [link] [number] TO ........ 

where name is a node name and number is the link connection 

FUNCTION name returns a REAL result but is compiled for wrong calling 
convention 

A routine compiled for class TA can only be run on a T800 if it obeys the 
correct calling conventions. See the advice for Occam code given in 
section B.2.3. Alternatively re-compile your code for a T8 transputer. 

Illegal item in configuration code 

An illegal expression has been used in the configuration description. 
Check the description against the syntax definition, described in appendix 
A of the occam 2 Toolset User Guide. 
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Illegal Item inside CONFIG construct 

Check the configuration description against the syntax definition, 
described in appendix A of the Occam 2 Toolset User Guide. 

Illegal item inside MAPPING construct 

Check the configuration description against the syntax definition, 
described in appendix A of the Occam 2 Toolset User Guide. 

Illegal item inside NETWORK construct 

Check the configuration description against the syntax definition, 
described in appendix A of the Occam 2 Toolset User Guide. 

Illegal processor type "name" 

Supported processor types are; "T212" "T222" "T225" "M212" 

"T400" "T414" "T425" "T8G0" "T801" "T805" 

Implementation restriction: Cannot RETYPE INT constants on 16-bit 

processors; use INT16 

This is a constraint of the current configurer, see section A. 7 of the Occam 
2 Toolset User Guide. 

implementation restriction: Cannot declare name name inside a replicator 

Declarations of nodes, arcs, and edges may not appear inside a repli- 
cator. 

Implementation restriction: Cannot use INT constant arrays on 16-bit 
processors; use INT16 

This is a constraint of the current configurer, see section A.7 of the occam 
2 Toolset User Guide. 

Implementation restriction: Cannot use replicator name in channel abbrevi- 
ation outside a PROCESSOR construct 

You have encountered an implementation restriction. 

Implementation restriction: INT constant overflows on 16-bit processors; 

use INT16 

This is a constraint of the current configurer, see section A.7 of the Occam 
2 Toolset User Guide. 

Implementation restriction: root NODE name must not be an array element 

You have encountered an implementation restriction. 
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Left hand side of mapping must be of type CHAN 

Channels are mapped onto anARC, with a statement of the following form: 

MAP channeUist ONTO arc 

where channeUist is a list of channels previously declared to have type 

CHAN. 

Left hand side of mapping must be of type NODE 

Logical processors are mapped onto a physical processor, with a state- 
ment of the following form; 

map processor.list onto node 

where processorJist is a list of logical processors previously declared as 
NODE types. 

Link name[\mk][number] has already been connected 

Check any previous connect statements to identify what 

link name[liiik][number\ is connected to. 

Link number number is illegal for this NODE 

T400 and M21 2 transputers have just two links, identified and l. A!l other 
transputers in the current range have four links, numbered 0, 1, 2 and 3. 

Location attributes ignored because re-ordering isn't enabled 

Use the RE command line option to enable the location attributes. 

Multiple CONFIG constructs not permitted 

The CONFIG keyword introduces the software description, which is a PAR 
or PLACED PAR and should include PROCESSOR statements defining all 
required software processes. 

Multiple MAPPING constructs not permitted 

All MAP statements should appear in one section introduced by the 
mapping keyword. Any attributes used to control the use of memory or 
routing should also be included in this section. 

Multiple NETWORK constructs not permitted 

All statements describing the connectivity and attributes of physical nodes 
should be placed in one section, introduced by the network keyword. 

NODE name has not been mapped 

Check your mapping description, a logical processor has been declared 
but not mapped to a physical processor. 
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No CONFIG construct 

The software description is missing or has not been introduced by a 
CONFIG keyword. 

No NETWORK construct 

The network description is missing or has not been introduced by a 
network keyword. 

No NODE has been specified as root 

Configurations which are for boot-from-ROM application must have one 
physical node defined to be the root transputer. This is performed using the 
root attribute in a SET statement. 

No hardware route exists from processor name for channel name 

There is no direct link available for channel name to use. Because through- 
routing has been disabled by the nv command line option an indirect route 
cannot be established. 

No priority expression permitted when mapping CHANs 

The priority expression pri can only be used when mapping logical 
processors onto physical processors. The priority expression relates to the 
software process which will run on the processor 

Not enough links from processor name for channel name 

The NV command line option has been specified, disabling virtual routing. 
This means that only one channel can be placed in each direction, onto 
each link specified in the hardware description. 

Ordering attributes ignored because re-ordering isn't enabled 

Use the re command line option to enable the order attributes, 

PRI expression nn must evaluate to or 1 

Priority expressions are introduced by a pri keysword in a MAP statement. 
pri expressions may take one of two integer values; either indicating 
high priority or 1 indicating low priority. 

Priority expression of mapping must be of type INT 

pri expressions may take one of two integer values; either Indicating 
high priority or 1 indicating low priority. 

Process evaluates to STOP 

The logic within the configuration description itself evaluates to a STOP 
and will therefore not execute. 



72TDS367 01 March 1993 



2 occonf ■ Occam configurer 45 

Process mapped at high priority may not contain a PRI PAR 

The logic of the MAP statement which includes the PRI expression conflicts 
with the internal logic of the program which uses a PRI par. 

Processor type has already been set for NODE name 

Node name already has the type attribute set. Check the hardware 
description. 

Processor type has not been set for NODE name 

The attribute type is a mandatory node attribute and should be set in the 
hardware description for NODE name. 

ROM memory size has not been set for root NODE 

The size of ROM attached to the root node must be specified using the 
romsize attribute. (The root node is the node which has the root attribute 
set). 

Right hand side of mapping must be a physical NODE 

Logical processors are mapped onto a physical processor, with a state- 
ment of the following form: 

map processor.Iist ONTO node 

where node is a physical node declared within the hardware description. 
Right hand side of mapping must be of type ARC 

Channels are mapped onto an arc, with a statement of the following form: 

MAP channel, list ONTO arc 

where arc is a named link declared within the hardware description. 

Right hand side of mapping must be of type NODE or ARC 

MAP statements are used to map logical processors onto physical proces- 
sors or channels onto named links called ARCS, The statement takes the 
form: 

MAP processor.Iist ONTO node 

where node is a physical node declared within the hardware description. 

OR: 

MAP channeUist ONTO arc 

where arc is a named link declared within the hardware description. 
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SET expression must be of type NODE 

The SET expression is used to set attributes for physical processors, ft 
takes the form: 

SET device (attribute. assignment) 

where device is a node name. 

Too many channels inputting on ARC name 

An ARC can carry a maximum of two channels, one in either direction. It is 
a dedicated link i.e. one which will not be used by virtual channels. 

Too many channels outputting on ARC name 

An arc can carry a maximum of two channels, one In either direction. It is 
a dedicated fink i.e. one which will not be used by virtual channels. 

Unknown attribute name name 

The attribute name used is not supported by the language. Valid attributes 
are: 

link linkquota location, code location. ws location. vs 
memsize nodebug noprofile order. code order. ws order. vs 
reserved romsize root routecost tolerance type 

Further information can be found in appendix A of the Occam 2 Toolset 
User Guide, 

Value must be in range to n for attribute name 

Attribute name has been incorrectly specified. 

WITH expression must be of type ARC 

The only configuration statement that a with expression may appear in, 
is a connect statement. This is used to connect an ARC with a link connec- 
tion. It takes the form: 

'connect edge to edge [WITH arcname] ' 
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collector 



This chapter describes the code collector tool icollect which generates an 
executable file for a single or multitransputer program from a configuration data 
file, or for a single transputer program directly from a linked unit. The tool is also 
used to create files for i npui to the EPROM programmer tool ieprom, and to create 
fifes that can be dynamically loaded by a user program. 



3.1 Introduction 

icollect generates bootable files for transputer programs, and other execut- 
able files in special formats. 

Bootable files are transputer executable files that can be directly loaded onto the 
transputer hardware down a transputer link. The bootable file contains all the 
information for loading and running the program on a specific network of proces- 
sors, including data that controls the distribution of code on the network, and self- 
booting code for each processor. Bootable programs are therefore self-distributing 
and self-starting when they are sent down a transputer link. 

Recommended program development for single and multitransputer programs is 
to create a configuration data file (i.e. binary file) and to use this as input to the 
collector. The configuration data file describes the placement of processes and 
channels on the processor network in a special format which can be read by the 
collector. They are created from configuration descriptions by the configurer. 

Single transputer programs can by-pass the configuration stage and use a single 
linked unit as input. The collector then adds bootstrap and system code for a single 
processor. Unconfigured programs can only run on a single transputer. This 
method of program development Is not recommended and may not be supported 
in future toolsets. 

icollect can be directed to generate output files in a special format for proces- 
sing by the ieprom tool, and executable code with no bootstrap orsystem process 
information, intended for dynamic loading by a supervisory program. 

The command line default is to assume input from a configuration binary file. 
Special format outputs are selected by specifying command line options. 

The main inputs and outputs of the collector tool for bootable programs are shown 
below. 
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3.2 Running the code collector 



Unconfigured program (using 'T' option): 




Configured processor program: 
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3.2 Running the code collector 

The code collector is invoked using the following command line: 

► icollect filename {options} 

where: filename is a configuration data file created by a configurer or a single 
linked unit created by ilink. Only one filename may be given on the 
command line. 

options Is a list of the options given in Table 3,1 . 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upperor lowercase and can be given in any 
order. 

Options must be separated by spaces. 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 
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Option 


Description 


B filename 


Uses a user-defined bootstrap loader program in place of the 
standard bootstrap. The program is specified by filename and 
must conform to the rules described in appendix E. 
This option can only be used with the Y option {unconfigured 
mode) and cannot be used with the *ra' and 'RO' options. 


BH 


Instructs the tool to use a different bootstrapping scheme, 
which uses the bottom of memory, see section 3.9. 

This option is only valid for configured programs i.e. when the 
'T p option is not used. 


c filename 


Specifies a name for the debug data file. A filename must be 
supplied and is used as given. 

This option can only be used with the 'T J option (unconfigured 
mode) and cannot be used with the 'D' or 'K' options. 


CM 


Instructs the collector to add a bootstrap which will clear 
memory during the booting and loading of the transputer 
network. Intended for use with parity-checked memory (see 
section 3.5). 


D 


Disables the generation of the debug data file for single trans- 
puter programs. This option can only be used with the 'T 1 option 
(unconfigured mode). 


E 


Changes the setting of the transputer Halt On Error flag. HALT 
mode programs are converted so that they not stop when the 
error flag is set, and non HALT mode programs to stop when 
the error flag is set. 

This option can only be used with the 'T* option (unconfigured 
mode). 


I 


Displays progress information as the collector runs. 


K 


Creates a single transputer file with no bootstrap code. If no file 

is specified the output file is named after the input filename and 

given the .rsc extension. 

This option can only be used with the r T' option (unconfigured 

mode). 


M memorysize 


Specifies the memory size available (in bytes) on the root 
processor for single transputer programs, memorysize is 
specified in bytes and may be given in decimal format (option- 
ally followed by 'K' or W to indicate Kilobytes or Megabytes 
respectively), or it may be specified in hexadecimal using the 
'#' or '$' prefixes. 

This option can only be used with the 'T' option (unconfigured 
mode} and results in a smaller amount of code being produced 
(see section 3.4). 



72TDS367 01 



March 1993 



50 



3.2 Running the code collector 



Option 


Description 


filename 


Specifies the output file, A filename must be supplied and is 
used as given. {See section 3.2.4). 


P filename 


Specifies a name for the memory map file. A filename must be 
supplied and is used as given. The file extension .map should 
be used when the file is to be used as input to imap, see chapter 
12. 


RA 


Creates a file for processing by ieprom into a boot from ROM 
file to run in RAM. If no output file is specified the filename is 
taken from the input file and given the ,btr extension. 

This option is only necessary when using the Y option (uncon- 
figured mode) to create a ROM code file. 


RO 


Creates a file for processing by ieprom into a boot from ROM 
file to run in ROM. If no output file is specified the filename is 
taken from the input file and given the .btr extension. 

This option is only necessary when using the ( T' option (uncon- 
figured mode) to create a ROM code file. 


rs romsize 


Specifies the size of ROM on the root processor in bytes. Only 
valid when used with the 'ra' or 'RO r options. 

romsize is specified in bytes and may be given in decimal 
format (optionally followed by Tc' or W to indicate Kilobytes or 
Megabytes respectively), or it may be specified in hexadecimal 
using the '#' or '$' prefixes. 

This option is only necessary when using the 't' option (uncon- 
figured mode) to create a ROM code file. 


s stacksize 


Specifies the extra runtime stack size in words for single trans- 
puter programs. {For Occam programs this option refers to 
stack. buffer, see section 3,4,2 for details). 

stacksize is specified in words and may be given in decimal 
format (optionally followed by 'K 1 or *M' to indicate Kilowords or 
Megawords respectively), or it may be specified in hexadecimal 
using the '#' or '$' prefixes. 

This option can only be used with the 'T' option. 


T 


Creates a bootable file for a single transputer. The input file 
specified on the command line must be a linked unit. This 
option can not be used for C programs which are linked with the 
reduced runtime library. 


Y 


Disables interactive debugging with idebug and reduces the 
amount of memory used. (See section 3.11). 

This option can only be used with the Y option (unconfigured 
mode). 



Table 3.1 icollect command line options 
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3.2.1 Examples of use 

Example A (unconfigured program mode): 

UNIX based toolsets: MS-DOS/VMS based toolsets: 

ice hello tec hello 

ilink hello.tco -f cnonconf.Ink ilink hello.tco /f cnonconf. Ink 

icollect hello. lku -t icollect hello. lku /t 

iserver-sb heilo.btl-se iserver/sb heilo.bil/se 

Example B (configured program mode): 

UNIX based toolsets: MS-DOS/VMS based toolsets: 

ice hello ice hello 

iiink helloAco -f cstartupJnk ilink hello, too ft cstartupJnk 

icconf hello.cfs icconf heiio.cfs 

icollect hello. cfb icollect hello. cfb 

iserver-sb heilo.btl-se iserver/sb hello.btl/se 

Note: single transputer programs linked with the reduced runtime libraries cannot 
be linked and collected with the 'T' option, they must be configured, 

3.2.2 Default command line 

Commonly used command line parameters can can be defined for the tool using 
the ICOLLECTARG environment variable. Parameters specified in this way are 
automatically added to the command line when the tool is run. 

Parameters in ICOLLECTARG must be specified using the syntax required by the 
command line. 



3.2.3 Input files 

The input file to icollect is either a configuration data file generated by a confi- 
gurer, or a linked unit generated by ilink. By default the collector assumes a 
configuration data file; for single transputer programs the input file may be a linked 
unit, in this case the 't' option must be given. 

Input files of an incorrect format generate an error message and no output is 
produced. 



3.2.4 Output files 

The output produced by the tool depends the type of file input to the collector and 
the collector options used. 
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Specifying an output filename 

An output filename can optionally be specified using the option, followed by a 
filename, which will be used as given. If the option is not used, the input filename 
wilf be used with an extension added indicating the file type, see below. 

Default case 

The default output file is a binary file that can be loaded directly onto the transputer 
hardware down a transputer link. This type of file is known as a boot from link 
program. By default the file is given the ,btl extension, 

Boot-from-ROM/RAM 

Boot-from-ROM programs output is generated by using the appropriate command 
line options; RO for boot-from-ROM; RAfor boot-from-RAM. By default the file will 
be given the .btr extension. 

C and FORTRAN programs must be configured, prior to using icoliect, in order 
to generate boot-from-ROM or RAM output. Occam boot-from-ROM or RAM 
output can be generated from either configured or unconfigured input. 

Dynamically loadable output 

Dynamically loadable code is generated by using the K command line option. By 
default the file is given the . rsc extension. 

Dynamically loadable code file may only be generated when the input to the 
collector is a linked unit and the T option is used, i.e. this type of output can only 
be produced for the unconfigured case. 

Memory map files 

A memory map file may be generated, in addition to the normal output, by speci- 
fying the ( P' option. The format of these files is described in section 3,10, 

Debug data file 

For unconfigured transputer programs only, the collector automatically generates 
a configuration binary file for use by the debugger By default the filename stem 
is taken from the output file and the extension '.cfb' is added. If the 'C* option is 
specified then the filename given is used, as supplied. Generation of the debug 
data file can be disabled with the 'D' option. 

3.3 Program interface for occam unconfigured programs 

For programs which are loaded onto a single transputer, the program interface 
must conform to the appropriate format, depending on whether or not memory size 
is specified on the collector command line. 
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3.3.1 Interface used for T option 

occam programs which are collected with the T option, without specifying merno- 
rysize (using the M option), must use one of the following formats of procedure 
declaration: 

FROC program (CHAN OF SP from. link, to. link, 
[]INT user. buffer} 

PROC program {CHAN OF SP from. link, to. link, 

[]INT user. buffer, stack. buffer) 

where: from, link and to. link are the input and output channels respectively 
of the transputer link, down which the transputer was booted. 

user .buffer is the free memory buffer. 

stack. buffer is a buffer allocated at the base of memory by the 
collector, whose size is determined by the s option. If the s option is not 
specified when icollect is invoked this buffer will be of size zero. 

3.3.2 Interface used for 'T' and *M' options 

In the case where both the Y and to' options are used, the program must conform 
to one of the following procedure declarations: 

PROC program (CHAN OF any protocol from, link, to. link, 

HINT user. buffer) 
PROC program (CHAN OF any protocol from, link, to. link, 

[JINT user .buffer, stack. buffer) 

where: The channel protocol can take any valid type. 
The other variables are as defined above. 



3.4 Memory allocation for unconfigured programs 

The memory allocation outlined in this section applies only to single processor 
programs collected with the *T' option and without the 'K' option. For configured 
programs the layout of code and data in memory is determined by the configurer 
For programs generated with the *T* option the layout is determined by the 
collector. The details of memory use depend on the language used and the options 
to icollect, this is described below. 

Memory which is not reserved by the system for program code and data (known 
as free memory) can be made available to a user application. For C programs this 
is used for the heap and, optionally, the stack. In the case of a single transputer 
Occam program the free memory passed as an array. 

To calculate the actual memory available, the loader program in the bootable file 
first reads the total memory size from the host environment variable iboards ize. 
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This communication with the host is performed after the program has been loaded 
onto the transputer board but before the program is started. The size of the free 
memory is given by iboardsize minus the combined program code and data 
space required. 

The process code which reads IBQAkdsize requires approximately 3.5 Kbytes 
of memory. This process is executed and terminated before the user program 
runs, and the segment of free memory that the process uses is then returned to 
the user program. Therefore when the user program executes it will not know 
whether the process was present or not. 

When the *M' option is used to specify the memory size, iboardsize is not read 
and therefore the total amount of memory required when loading the program will 
be approximately 3.5 Kbytes less. 

A memory map file may be obtained by specifying the 'P' command fine option. The 
content of memory map files is described in section 3.10. 

3,4,1 C and FORTRAN programs 

ForC programs the bootstrap loader must allocate memory for static data, stack 
and heap areas. FORTRAN programs have similar requirements and are handled 
in the same way. 

When the collector 'S' option is specified the program's stack is placed at the 
bottom of memory. When the 'S' option is not specified a stack area is allocated 
by the runtime system, typically at the top of free memory. 

Areas for static data and heap are always allocated by the language's runtime 
system at the bottom of free memory. The heap area grows upwards, towards the 
top of memory, and the stack grows downwards. 

Figure 3.1 shows the memory map layouts for programs with and without the stack 
requirement specified by the user. 

The value of LoadStart is described in section 3.10, 
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Figure 3.1 Memory maps for C and FORTRAN 



3.4.2 occam programs 
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Figure 3.2 Memory map for Occam program 
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An occam program requires space to be allocated for code, workspace and, poss- 
ibly, vector space. Programs can also be passed one or two arrays as parameters; 
one (always available) provides access to the free memory. The other is optional 
but, if used, it is placed at the bottom of the memory map to provide access to the 
transputer's fast internal RAM. This array is known as the stack. buffer. The 
default bootstrap loader attempts to optimize placement of the program's, and its 
own, code and workspace. If present, the stack. buffer array is placed at the 
bottom of memory (at LoadStart). This is followed in order by the workspace, 
code, vector space (if used) and free memory. The 's' option allows space to be 
reserved in the internal RAM. 

Figure 3.2 shows the memory map of the loaded Occam code as created by the 
default bootstrap loader. 

3.4.3 Memory initialization errors 

While the loader is executing the memory initialization process, described above, 
warning messages may be obtained which have the following format: 

Warning-SystemA- message 

where: message can be one of the following: 

IBOARDSIZE, unable to read 

IBOARDSIZE environment variable is not defined correctly. 
number, illegal format number 

The value specified for iboardsize is in the wrong format, 

illegal 16 bit memory size, set to zero 

The value of IBOARDSIZE is greater than 64K when a 1 6 bit processor 
is being used. The memory size has therefore been set to zero. 

negative memory size, set to zero 

A negative value was specified for IBOARDSIZE, which has been set 
to zero. 

unable to reset free memory 

The loader cannot return the memory it has used to the user. 

All the above errors are generated by the system process at runtime. 

3.4.4 Small values of IBOARDSIZE 

When the T option is used, very small values of iboardsize (including zero) are 
detected at runtime and prevent the program from being run. iboardsize is read 
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at runtime, not by the collector at build time. Small values of ibqardsize cause 
the collector to generate a warning message but do not prevent the generation of 
a bootable file. 

iboardsize must be & to the total memory requirements of the user program 
being executed. 



3.5 Parity-checked memory 

If any processors in the network use parity-checking on external memory (typically 
using the T426) then it is essential that that memory is initialized (written to) before 
it is read. Reading from an un-initialized location is likely to cause a parity error. 
Internal memory is not parity-checked, so a bootstrap program can always get 
started, but the initialization must be done before any program using external 
memory is run. Therefore the initialization of memory must be done during the 
booting and loading of the processors. 

There is an option to the collector, 'CM', which instructs the collector to use a boot- 
strap that clears memory on each transputer before the application code is 
executed. This must always be used when collecting programs for a network that 
contains one or more T426s. When selected, the 'CM' option applies to all proces- 
sors in the network, not just to T426s. 

In order to clear the memory on a processor, it is necessary for the bootstrapping 
sequence to know the size of the memory. There are four cases to consider 

1 A configured program. 

Mere the memory size is known at configuration time, and is specified by 
the user in the configuration source file. The bootstrapping sequence 
produced by the collector will clear the amount of memory specified (in the 
configuration source file) before booting the application. 

2 A collected program with fixed memory size. 

The collector may be used, with the V option, to produce a bootable file 
from a single linked unit. The amount of memory on the processor may be 
specified with the If option. In this case the bootstrapping sequence will 
dear the amount of memory specified (with the 'M' option) before booting 
the application. 

3 A collected program with variable memory size, booted from link. 

If the collector is run with the 'T' option, but without the 'tf option, the 
memory size is known only at runtime. The memory size is found out at 
runtime using the environment variable IBOAFDSIZE. In this case the 
bootstrapping sequence will clear memory up to the minimum required to 
boot the program. After booting, the value of IBOARDSIZE will be read and 
the remaining memory will be cleared. 
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4 A collected program with variable memory size, booted from ROM. 

If the collector is run with the 'T' option, but without the 14" option, and the 
program is booted from ROM, then the memory size is not known at all. In 
this case the bootstrapping sequence wilE clear enough memory for the 
minimal requirements of the application. It is then the user program's 
responsibility to clear any additional memory required. 

Initialization of memory is carried out regardless of the processor type; memory 
is initialized even if the processor is not a T426. So if the 'CMf option is selected 
every processor's memory in the network will be initialized (including 16-bit trans- 
puters). In the case of the T426, the bootstrap code also clears the parity registers 
by reading them before the program starts. 

3.6 Non-bootable files created with the K option 

Files created with the 'K' option are non-bootable files which can be dynamically 
loaded or manipulated by a program at runtime. Non-bootable files cannot be 
loaded and run on transputer hardware in the normal way. 

3.6.1 File format 

Non-bootable files consist of program code preceded by a specific sequence of 
data words which provide runtime information. The sequence of data words and 
code blocks is summarized in table 3.2. Descriptions of the more important data 
items are given in table 3.3. 



Data 


Number of bytes occupied 


Unit 


interface descriptor size 


Four 


bytes 


Interface descriptor 


Set by above 


- 


Compiler id size 


Four 


bytes 


Compiler id 


Set by above 


- 


Target processor type 


Four 


- 


Version number 


Four 


- 


Program scalar workspace requirement 


Four 


words 


Program vector workspace requirement 


Four 


words 


Static size 


Four 


words 


Program entry point offset 


Four 


bytes 


Program code size 


Four 


bytes 


Program code block 


Set by above 


- 



Table 3.2 Sequence of code segments in non-bootable files 
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Target 



A value indicating the processor type or transputer 
class for which the program was compiled. Set by 
compiler options or by default Possible values and 
their meaning are: 



Value 


Applies to: 


2 


T212 f T222,T225, M212 


4 


T414 


£ 


T800,T801,T805 


S 


T425 P T400 ( T426 


10 


TA 


11 


TB 



Version 



Scalar workspace 

Vector workspace 

Static size 

Entry point offset 

Code size 
Code 



The format version number of the file. This can be 
either 10 or 11 in TCOFF files. For C and FORTRAN 
programs this value is 11, which indicates that the 
'Static size' parameter (below) is present. For occam 
programs the value is 10, indicating no static data; the 
parameter list will also not be present. 

Specifies the size of the workspace required for the 
linked program's runtime stack. 

Specifies the size of the workspace required for the 
linked program's vector (array) data. 

Specifies the size of the static area (only present if the 
file format version number is 11). 

Indicates the offset in bytes of the program entry point 
from the base of the code block. 

Indicates the size of the program code in bytes. 

The program code. 



Table 3.3 Details of code segments in non-bootable files 

3.7 Boot-from-ROM output files 

Boot-from-ROM output files are either generated by using the collector options 
'RA' or *RO' for unconfigured programs or by configuring a program to boot from 
ROM, prior to collecting. (The configurer also has *RA' and 'RO' command line 
options). 

The boot-from-ROM files contain code that can be loaded into EPROM using the 
ieprom tool. The code may be run on the root transputer of a network; processors 
on the network connected to the root transputer are booted from the root transput- 
er's links. 

'RA' generates code which is executed from RAM.The code is copied from ROM 
into RAM at runtime. f RO' generates code which is directly executed from ROM. 

RAM executable code can be used for applications which are to be executed from 
fast RAM, and for code which may be user-modified. ROM executable code may 
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3.8 Alternative bootstrap loaders for unconfigured programs 



require no external RAM for programs which use small amounts of data and can 
be used to create a truly embedded system. 

3.8 Alternative bootstrap loaders for unconfigured programs 

If not otherwise specified, icollect uses the standard INMOS primary bootstrap 
loading sequence. The correct code for the application program is chosen auto- 
matically from a library of bootstraps compiled for different transputer types and 
error modes. 

The collector can be directed to use other bootstrap loader programs defining 
different loading sequences by specifying the 'B' option. This option directs the 
collector to append a user-defined loader program in place of the standard boot- 
strap code. 

User-defined bootstraps must comply with the format used by the standard fNMOS 
loader. The source of the standard INMOS Network Loader is supplied with the 
toolset. The source is fully commented and can be used as a template to design 
and code your own loading sequence. 

3.9 Alternative bootstrap schemes 

When building for a configured network, the collector uses a bootstrapping 
scheme which makes use of the top two hundred bytes of memory. This memory 
is required to load the last few bytes of application code prior to its execution. The 
memory region becomes available to the user once their application is running. 

This scheme does not remove memory from the user's environment on a perma- 
nent basis and it facilitates the absolute placement of code and data by the user. 
See the User Guide for details. 

The user can tell the collectorto use a different booting scheme by using the option 
'BM\ In this case the booting scheme permanently removes a section of memory 
from the user's environment and moves the value of LoadStart accordingly. This 
section of memory is never made available to the user. This booting scheme does 
not support the absolute placement of code and data by the user. 

The booting scheme invoked by the 'BM 1 option, is used by default for unconfigured 
programs i.e. those collected using the Y option. 

3.1 The memory map file 

A memory map file may be obtained by specifying the 'P' command line option, 
followed by a filename. Such files contain the memory layout for each processor 
in the network. 

The file layout takes the form of a list of code and data to be placed on respective 
processors. The right hand side of the file gives the start and end address followed 
by the size of each block. 
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The memory map file contains the following information: 

• icollect version data 

• For each processor the following details are given: 

o Processor type 

o Error mode (HALT or STOP} 

o LoadStart (lowest user memory address) 

o For each process on this processor the following is listed: 

□ Code, name of file, offset from start (decimal), start address and 
end address (hex), size (decimal), entry address (if any, in Hex) 

□ Workspace, start and end address (hex), size (decimal) 

□ Any other data requirements 

• Boot path for the network - only present if program is configured 

• Connectivity of the network - only present if program is configured 

The absolute addresses are calculated using LoadStart, which is the base of user 
memory. This varies for different processor types i.e. the value of LoadStart for 
a T4 processor is different to that for a T8. 

If the 'BM' option is used the memory from MemStart to LoadStart is used by the 
low ievel bootstraps and their workspace. 

When the 'BM' option is not used the value of LoadStart is determined by the 
configuration, see the reference chapter for the configurer, for further details. 

The addresses allocated to various data items reflect the command line options 
specified to the collector. Details of the memory map files for the following types 
of files are given below: 

• Unconfigured (single processor), boot from link programs targetted at a 
specific processor type. 

• Unconfigured (single processor), boot from link programs targetted at a 
processor class. 

• Configured, boot from link programs. 

• Boot from ROM (single and configured) 

The examples below demonstrate the map file format; they may change in detail. 

3.10.1 Unconfigured (single processor), boot from link 

Program targetted at transputer type 

The first memory map described in this section is for a program which is to be 
booted for a specific processor type, 
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3.10 The memory map file 



The example shown in Figure 3.3 was produced by the following command line: 

icollect -t hello. lku -s 400 -p hello. map (UNIX) 

icollect /t hello. lku /p /s 400 hello. map (MS-DOS/VMS) 

where: hello . lieu was produced by compiling and linking the example program 
hello . c for a T425 in the default halt-on-error mode. The compiled object 
file was linked with the C linker indirect file cnonconf . Ink because the 
example is for an unconfigured program. 

hello. map lists code and data segments to be placed on each processor (one 
in this case). For each process the workspace and vector space requirements are 
given together with the entry point of the process. Note that the first three 
processes listed are non-user processes; this will always be the case for this type 
of program. 



Icollect : INMOS toolset collector 
Sun Version 3.0. IT 

Memory map for processor T425 

Load Start is 80000168, HALT ON ERROR, Minimum memory size is 21056 
LOW priority INITSYSTEM process 'Init. system' 
Code from 'sysproc. lib' f file offset 9438 

#80Q001F8 

Entry address #80000lF9 

Invocation stack #8000Q1DB 

Workspace 480000168 



{30000418 

f8Q0001F0 
#B00001D8 



LOW priority SYSTEM process ' System. process. a' 
Code from ' sysproc. lib' , file offset 27180 

180004670 

Entry address 180004671 

Invocation stack #30004654 

workspace #80004 43C 

Vectorspaee #80005040 

HIGH priority SYSTEM process 'System. process .b' 
Code from f sysproc. lib' , file offset 45498 

#8000044C 

Entry address #80OO044C 

Invocation stack #80000430 

Workspace #80000418 



LOW priority USER process 

Code from 'hello. lku', file offset 2 

Entry address 
Invocation stack 
Workspace 
Extra 3tack 
Static 

Parameter data 



#80000858 

I300008B3 
#8C0OO86C 
J800007A8 
#80000168 
#8000443C 



#80005040 

$80004668 
#80004654 
#80005240 



#800004A8 

#80000444 
#80000430 



#8000427C 

#80000880 
#300008SC 
#800007A8 
#S000466A 



I8000427C #8000443C 



544 



24 

112 



2512 

20 

536 
512 



92 



2 Li 
24 



14836 

20 

196 

1600 

558 

443 



Figure 3.3 Memory map file for a single T425 processor program 
Program targetted at transputer class 

The second memory map described in this section is for a program which is to be 
booted for processor classes TA or TB. 
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The example shown in Figure 3.4 was produced by the following command line: 

icollect -t hello. Ifcu -p hello. map (UNIX) 

icollect /t hello. lku /p hello. map (MS-DOS/VMS) 

where: hello, lku was produced by compiling and linking the example program 
hello. c for class TA in the default halt-on-error mode. The compiled 
object file was linked with the C I inker indirect file cnonconf . Ink because 
the example is for an unconfigured program. 



icollect : INMOS toolset collector 
Sun Version 3.0.17 

Memory map for processor o TA 

Load Start is UNKNOWN, HALT ON ERROR, Minimum memory size is 20180 
LOW priority INITSYSTEM process ' Init, system' 
Code from 'sysproclib' , file offset 10420 



Entry address 
Invocation stack 
Workspace 

LOW priority SYSTEM process 'System. process. a' 
Code from ' sysproc.lib' , file offset 30561 

Entry address 
Invocation stack 
Workspace 
Vectorspace 

HIGH priority SYSTEM process 'System. process. b' 
Code from 'sysproc.lib', file offset 45888 

Entry address 
Invocation stack 
Workspace 

LOW priority USER process 

Code from 'hello. lku', file offset 2 

Entry address 
Invocation stack 
Workspace 
Static 

Parameter data 



#3D43 


J3F68 


544 


#3D49 






#3D28 


I3D40 


24 


I3CB8 


#3D23 


L12 


#419C 


#4B6C 


2512 


#413D 






#4180 


#4194 


20 


I3F68 


#4180 


536 


14B6C 


#4D6C 


512 


#34 


#30 


92 


#34 






#18 


#2C 


2C 


40 


#18 


24 


t£Q 


#3AFS 


14372 


HOB 






fC4 


#DS 


20 


#0 


#C4 


156 


#3F68 


#4196 


558 



#3AF8 



#3CB8 



448 



Figure 3.4 Memory map file for a single TA processor program 

The memory layout of user's code and data is the same as for the previous 
example, except that no space is allocated for the extra stack (because extra stack 
was not requested on the command line). LoadStart, from which the start and end 
addresses are calculated, can only be calculated at runtime. This is because the 
value of MemStart cannot be determined at collect time. The numbers given, in 
place of absolute addresses are offsets from LoadStart. 
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3.10.2 Configured program boot from link 



lcollect : IHMOS toolset collector 
Sun Version 3,0.17 



Memory map for 'Single' processor T425 

Lead Start is 800QOOAQ, HALT ON ERROR, Minimum memory size is 7323G 

HIGH priority IKITSYSTEM process 'Init. system, simple' 
Code from * sysproc. lib' , file offset 13366 

♦800000E4 #80000158 116 
Entry address #800000E4 

Invocation stack #800000CO #B0O00OE4 36 

Workspace #800000AO #800000CG 32 

HIGH priority OVERLAYED SYSTEM process 'System. process. b' 
Code from ' sysproc. lib' , file offset 44718 

#80000184 #30000lE0 92 
Entry address #30000184 

Invocation stack #30000170 #80000184 20 

Workspace #80000158 #80000170 24 

LOW priority USER process 'Simple' 
Code from 'hello. lku' , file offset 2 

Entry address 
invocation stack 
Workspace 

Static 
Heap 

Parameter data #80011024 #80011050 300 

Boot path for network 

Boot processor down link from HOST 



#80001178 


#B0OQ4B6C 


14836 


#B00011A3 






#80001164 


#30001178 


20 


#8000CCAG 


#30001164 


4232 


#80004B6C 


#30005424 


2232 


#80005424 


#80011C24 


51200 



V 



Connectivity for network 

Connect HOST to processor link 



Figure 3.5 Memory map file for a configured T425 processor program 

The example shown in Figure 3.5 was produced by the following command line: 

icollect hello. cfb -p hello. map (UNIX) 

icollect hello, cfb /p hello. map (MS-DOS/VMS) 

where: hello . cfb is the configuration binary file produced by the configurer for 
the single processor 'Hello World' example program introduced in the ANSI 
C Toolset User Guide. 

The Memory map for the configured program is similar to that produced for uncon- 
figured transputer programs except that it has two additional configuration 
sections at the end of the file. The Boot path for the network lists processors in the 
order in which they are to be booted. The Connectivity for network lists the link 
connections between the processors. 
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3.10.3 Boot from ROM programs 

There are four cases for this type of program: 

• Unconfigured (single processor), boot from ROM, run in RAM 

• Unconfigured (single processor), boot from ROM, run in ROM 

• Configured program, boot from ROM, run in RAM 

• Configured program, boot from ROM, run in ROM 

The memory maps for each of these are summarized below. 

Unconfigured (single processor), boot from ROM, run in RAM 

The memory map for this case will have the same layout as the single processor 
boot from link programs. 

Unconfigured (single processor), boot from ROM, run in ROM 

It is not known at collect time where in memory the ROM is to be placed. Therefore, 
the start and end addresses of the code segments are given as offsets from the 
start of ROM, and are annotated as such, items such as workspace will have abso- 
lute addresses allocated, if the program is targetted at a specific processor type. 

Note: for C programs the runtime startup system would require modification first, 
in order to provide the system with details of heap and stack etc. 

Configured program, boot from ROM, run in RAM 

The layout of the memory map for this case will be the same as that for the boot 
from link configured program. This is because everything (code and data) is copied 
into RAM. 

Configured program, boot from ROM, run in ROM 

For this case the root processor will be shown in the same format as the single 
processor case, run in ROM; some memory locations being expressed as offsets 
from the beginning of ROM. 

The other processors in the network will appear as in the boot from link case. 

The example shown in Figure 3.6 was produced by the following command line: 

icollect hello. cfb -p hello. map (UNIX) 

icollect hello. cfb /p hello. map (MS-DOS/VMS) 

where: hello . cfb is the configuration binary file produced by the configurer, for 
the single processor'Hello World' example program introduced inthe.ANS/ 
C Toolset User Guide, The configurer 'RO' p lis' and 'p 1 options were used 
to create a boot from ROM input file for the collector. 
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#DF 


#3AD3 


14836 


#10A 






#80001164 


♦80001178 


20 


tSOGOOOAO 


#30001164 


4292 


#80001178 


#80001A30 


2232 


I8O001A30 


#8000E230 


51200 


#8Q00E230 


#8000E35C 


300 



icollect : INMOS toolset collector 
Sun Version 3,0.17 



Memory map for 'Single' processor (Booting and running in ROM) T425 
Load Start is 800O00AO, HALT ON ERROR, Minimum memory size is 58204 

HIGH priority INITSYSTEM process ' Rom. Init, system. simple' 
Code from ' sysproclib' , file offset 16750 

ROM OFFSET #3AD3 #3B6F 156 

ROM entry offset #3AD6 

Invocation stack #8000 0DCO #30 000QE4 36 

Workspace #aO00OOAO #80000000 32 

HIGH priority OVERLAYED SYSTEM process ' System. process. b' 

Code from ' sysproc.iib' , file offset 44718 

ROM OFFSET #3B6F #3BCB 92 

ROM entry offset I3B6F 

Invocation stack #SOO00OFC #80000110 20 

Workspace #8OQ0OOE4 #80OOO0FC 24 

LOW priority USER process 'Simple' 
Code from ' hello. lku' , file offset 2 

ROM OFFSET 

ROM entry offset 
Invocation stack 
Workspace 
Static 
Heap 

Parameter data 

Boot path for network 



Connectivity for network 
^ 

Figure 3.6 Memory map for program configured to boot from and run in ROM 

3.11 Disabling interactive debugging - ( Y' option 

The 'Y' collector option has two effects on the program being built: 

• tt disables interactive (breakpoint) debugging of the program 

* It reduces the amount of memory used. 

For programs compiled and linked for a specific transputer type, this option will 
cause icollect to produce a program that uses less memory. However, 
programs compiled and linked for transputer classes 'TA'or'TB' wifl not build when 
this option is used. This option is only valid for programs collected with the T option. 
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3.12 Error messages 

This section lists error messages generated by icollect. The messages are 
listed in alphabetical order under the appropriate severity classification. In all 
cases the introductory string (severity, and filename if appropriate) is omitted. 

icollect generates errors of severities Warning and Serious. Serious errors 
cause the tool to terminate without producing any output 

3.12.1 Warnings 

The following messages are prefixed with 'Warning-'. They are only generated 
when the 'T' option is used (single processor mode). 

Extra disable option on command line ignored 

The program has been configured with interactive debugging disabled 
and the 'Y' option specified to the collector is therefore superfluous. 

Flip error mode ignored with user bootstrap 

The £ E' option is ignored when a user-defined bootstrap is specified 
since the collector will only accept a single linked unit as a bootstrap. 

Program configured with interactive debugging enabled, option 
ignored 

The program has been configured with interactive debugging enabled 
and the T option has been specified to the collector The T option is 
ignored and the boot file is built. 

Strange board size for sixteen bit processor: Setting to zero 

The memory size specified exceeds the addressing capacity of a 1 6 bit 
processor (64 Kbytes). The collector uses a memory size of zero for the 
rest of the build. 

3.12.2 Serious errors 

The following errors are prefixed with 'Serious-'. 

Address space for target processor exhausted 

The address space required by the program is greater than 64Kbytes, 
the maximum addressable space on a 16-bit processor. 

Bootstrap file already specified 

More than one bootstrap file was specified. Only one file is allowed. 

Bootstrap filename too long 

The maximum length allowed for the bootstrap filename is 255 charac- 
ters. 



72TDS367 01 March 1993 



oB 



3.12 Error messages 



Bootstrap is greater than 255 byte in library file 

The library bootstrap is too large. This should only occur if the library 
file is invalid or corrupt. 

Cannot have both rom types 

'RA' and *ro' options are mutually exclusive and cannot both be speci- 
fied on the same command line. 

Cannot have configured and memory size 

The memory size option is incompatible with building a bootable 
program for a configuration binary file. 

Cannot have configured and non bootable file 

The collector cannot generate both a network loadable file and a non- 
bootable file simultaneously for the same program. 

Cannot have rom and non bootable file 

The collector cannot generate both a ROM-loadable file and a non- 
bootable file simultaneously for the same program. 

Cannot open file filename 

Host file system error. The file specified cannot be opened. 

Cannot patch parameter data for processor class 

The 'Y' option has been specified with a linked unit for a processor class. 
The collector cannot initialize some of the data without a linked unit for 
a specific processor type. 

Cannot use absolute placement and bottom of memory loader 

The user has specified bm to the collector but is using absolute code and 
data placement at configuration. This combination is not legal. 

Command line parsing error at string 

Unrecognized command line option. 
Debug file already specified 

More than one debug was file specified. Specify one only 

Dynamic memory allocation failure 

Memory allocation error. The collector cannot allocate the required 
amount of memory for its internal data structures. 

Error in writing to debug file 

Host file system error. The debug file could not be written. This 
message will only appear if the collector is invoked with the T option 
(unconfigured mode). 
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Expected end tag found not present in .cfb file 

A specific end tag is missing in the configuration binary file. Either the 
file is corrupted or the versions of icollect and configurer used are 
incompatible. 

Illegal tag found in .cfb file 

Incorrect format configuration binary file, recognized as an illegal tag. 
Either the file is corrupted or the versions of icollect and configurer 
used are incompatible. 

Illegal language type found in input file 

Source language used to create the file is not supported by the 
collector. Less likely, but possible, is that the file was created using an 
incompatible (possibly earlier) version of a tool. 

Illegal process type 

Unrecognized process type. Either the file has been corrupted or the 
versions of icollect and configurer used are incompatible. 

Illegal processor type 

Unrecognized processor type. Either the file has been corrupted or 
icollect and the configurer are incompatible. 

Illegal tag found in input file : Filename 

Incorrect format input file. The most likely reason for this error is that an 
incorrect file has been specified. Other less likely but possible explana- 
tions are that the file was created using an earlier or incompatible 
version of one of the tools, or that the file has become corrupted. 

Input file already specified 

More than one input file specified on the command line. 

Input file has not been linked filename 

The collector accepts only linked files, either directly when using single 
processor operation, or indirectly via entries in the configuration binary 
file. This message can be generated if the file was created using a 
previous version of a tool, or if the file is corrupt. 

Input file is of incorrect type: filename 

If the 'T option is specified (single processor program) the input file 
must be a single linked unit ( . lku type). If the 'T' option has not been 
specified the input file must be a configuration binary file (.cfb type). 

Input filename too long 

The maximum length allowed for the input filename is 256 characters. 
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Linked unit file in cffa and linked unit in input file found do not match: 

filename 

The Jinked file specified in the configuration binary and the one found 
the collector do not match. 

Linked unit module not found in: filename 

The required library module is missing or has been corrupted. This 
message is generated when an incorrect version of the library is 
installed. 

Memory requirement for build is greater than specified, an extra <n> 
bytes required at least 

The amount of memory specified on a processor is not enough for the 
program to execute. An extra <n> bytes are required at least. 

Memory size already specified 

Memory size must be specified once only. 

Memory size string invalid 

Memory size must be given in decimal or hex. Hex numbers must be 
introduced by '#' or '$'. 

Memory size string too long 

Specified memory size is too large. 

More than one parameter statements 

The collector expects only one parameter statement per processor 
Either the file has been corrupted or the versions of icollect and 
configurer used are incompatible. 

No debug and debug output file specified in command line 

Options 'd' (disable debug) and 'C (debug filename) cannot be used 
together. 

No input file specified 

One, and only one, input file must be specified on the command line. 

No parameter descriptor present in input file: filename 

The formal parameter descriptor in the input file is not present. This 
usually means that the process has not been Jinked with a main entry 
routine. This message will only appear if the collector is invoked with the 
'T' option (unconfigured mode). 

Output file already specified 

More than one output file was specified. Specify only one. 
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Output filename too long 

The maximum length allowed for the output filename is 256 characters. 
Parameter descriptor error in input file : filename 

The formal parameter descriptor in the input file is not of the correct 
form, indicating that the process interface is not one recognized by the 
collector. This message will only appear if the collector is Invoked with 
the T option (unconfigured mode). See section 3.3. 

Print map file already specified 

More than one print map file was specified. Specify one only. 
Program configured for boot from ROM command line is boot from link 

The specified configuration binary file was created for either ROM or 
RAM, and neither has been specified to icollect. 

Program configured for running in RA mode command line is RO mode 

Wrong mode specified, or incorrect option given to the configurer when 
the specified configuration binary file was created. RA and RO modes 
are mutually exclusive. 

Program configured for running In RO mode command line is RA mode 

Wrong mode specified, or incorrect option given to the configurer when 
the specified configuration binary file was created. RA and RO modes 
are mutually exclusive. 

Require at least <ny> bytes at the top of memory for bootstrapping on 
processor <n> 

The bootstrapping sequence requires an extra <ny> bytes at the top of 
memory. Once the bootstrapping has finished this memory is available 
to the user, 

Rom size already specified 

ROM size must be specified once only. 

Rom size in input file and command line do not match 

The ROM size specified on the command line does not match that 
specified to the configurer when the input file was created. 

Rom size not specified 

A ROM size must be specified because the input file is to be loaded into 
ROM. 
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Rom size string invalid 

ROM size must be given in decimal. 
Rom size string too long 

ROM size specified was too large. 
Stack size already specified 

Stack size must be specified once only. 
Stack size string invalid 

Stack size must be specified in decimal format. 
Stack size string too long 

Specified stack size was too large. 

Strange function or attribute for linked unit in : filename 

The collector has found an unfamiliar value in the input file. Either an 
old version of a tool was used in the creation ofthe input file, orthe input 
file has been corrupted. 

System error 

Host system error has occurred, probably when accessing a file. This 
message may be generated when a file is read and its contents seem 
to have changed or the file does not exist. 

Unexpected end of file : filename 

One ofthe files specified in the configuration binary has ended prema- 
turely, filename identifies the offending file. If the message 'Suspect 
corrupted file 5 is substituted for filename then the file is corrupted. 

User bootstrap not allowed when program is configured 

User defined bootstrap loaders can only be used with single processor 
programs. 

User bootstrap not allowed with rom option 

User defined bootstrap loaders cannot be used with ROM-loadable 
code. 

User bootstrap type does not match that of linked unit 

Either the target processor type orthe error mode ofthe bootstrap code 
does not match that of the input file. 

3.12.3 Fatal errors 

Internal error ^message text> 

An internal error has occurred this shoufd be reported to your local 
INMOS distributor or field applications engineer. 
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This chapter is a reference chapter for the network debugger tool idebug. It 
describes the command fine syntax and gives examples of the commands to use 
in different situations, tt provides detailed reference information about the 
debugger symbolic debugging functions and Monitor page commands, and 
provides a list of error messages. 

This chapter does not describe how to use the debugger, which is covered in 
Chapter 9 of the User Guide. 

4.1 Introduction 

The network debugger idebug is a comprehensive debugging tool for transputer 
programs. It can be run in post-mortem mode to determine the cause of failure In 
a halted program, or in interactive (breakpoint) mode to execute a program step- 
wise by setting breakpoints in the code. In either mode programs can be debugged 
from source code using the symbolic functions orfrom the machine code using the 
Monitor page commands 

Post-mortem debugging allows programs to be examined for the cause of failure 
after a transputer halts on error. The debugger locates the errant process in the 
program either by direct examination of the program image in transputer memory 
or by reading memory dump files* Processes running in parallel with the errant 
process anywhere on the network can be examined. 

Interactive breakpoint debugging allows programs to be executed in a stepwise 
manner under interactive control. Breakpoints can be set within the code to cause 
the program to pause for the inspection of variables, channels, and processes; 
variables can be modified and the program continued with the new values, 

The debugger can also be invoked on a dummy network to examine the static 
features of a program. The dummy network simulates the contents of memory 
locations and registers, and can also be used to explore the features of the 
debugger without running a real program. 

4.2 Debugging the root transputer 

idebug can be used to debug single and multitransputer programs. The tech- 
niques and commands to use when invoking the debugger differ slightly depending 
on whether or not the program (or a process forming part of the program) runs on 
the root transputer, and according to the debugging mode (post-mortem or break- 
point). 
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Two procedures are used to debug programs in post-mortem mode, depending on 
whether the application uses the root transputer. Programs that use the root trans- 
puter are referred to in this chapter as R-mode programs, and programs that do 
not use the root transputer are referred to as T-mode programs. Command line 
options are used to select the correct mode of operation for idebug. 

To avoid the need for a memory dump, programs can be skip loaded over the root 
transputer using iskip. Skip loading requires at least one extra processor in the 
network (which will be used by the debugger) but speeds up debugging consider- 
ably and is the recommended method where more than one processor is available. 
Skip loading is described in detail in chapter 15 of this manual. 

4.2.1 Board wiring 

Before any program can be debugged in post-mortem mode, the transputer's 
Analyse signal must be asserted once, and once only. Because different proce- 
dures must be adopted for programs which do and do not use the root transputer, 
the debugger cannot assert the signal automatically and so the appropriate 
iserver option must be specified on the idebug command line. 

Table 4.4 summarizes the command sequences to use for the two program modes 
on different board types. 

4.2.2 Post-mortem debugging R-mode programs 

Code running on the root transputer, and loaded with i server directly, is 
debugged in post-mortem mode from a memory dump file which is specified by the 
'R J option. The memory dump file must be created using the idump tool before the 
debugger is invoked. Other transputers in the network are debugged down links 
connected to the root transputer, in the normal way 

For R-mode programs, idump asserts the Analyse signal and the *SA' option is not 
required on the idebug command line. In fact a second assertion of the signal 
would cause data in the memory to become corrupted. If idump is not used before 
the debugger is run then the debugger cannot load onto the root transputer and 
a server error is reported. 

A description of the idump tool can be found in chapter 5 of this manual. 

4.2.3 Post-mortem debugging T-mode programs 

T-mode programs are loaded using iskip and subsequently debugged using the 
T' option to specify the root transputer link to which the network is connected. The 
"sa" server option must also be added to the idebug command line in order to 
assert Analyse, 

If the 'SA' option is not given, the debugger can not be booted onto the root trans- 
puter and the server aborts with an error message. The debugger should then be 
re-invoked with the correct options. 
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4.2.4 Post-mortem debugging from a network dump fife 

To suspend a post-mortem R or T debugging session without losing the original 
context, the Monitor page QT] command can be used to dump the entire state of 
a network into a network dump file. The debugger can then be invoked using this 
file, without being connected to the network (although one transputer will still be 
needed to run the debugger). 

Note: This option will only work for programs that have not been interactively 
(breakpoint) debugged. 

Memory dump files and network dump files are not the same: the former contains 
a single processor's memory image while the later contains data about a complete 
network (they are also in different formats). The ilist tool can be used to deter- 
mine the format of a dump file. 

4.2.5 Debugging a dummy network 

The debugger may be used to debug a program using dummy data. Using the 
debugger command fine 'D J option which simulates the contents of memory loca- 
tions and registers, static features of a program may be examined. This is useful 
to determine processor connectivity and memory mapping for each processor in 
the network. Because memory locations etc. are simulated, this option only 
requires the root transputer in orderto execute the debugger (even when used with 
a bootable file for a network of transputers). 

The 'D* option may also be used to explore most features of the debugger without 
running a program. 

4.2.6 Methods for interactive breakpoint debugging 

Interactive mode breakpoint debugging does not require use of the memory dump 
tool because the program is automatically skip loaded over the root transputer 
where the debugger is running. However, like all skip loads it requires an extra 
processor on the network. 

4.3 Running the debugger 

The debugger is invoked using the following command line: 

► idebug bootableffle {options} 

where: bootahlefile is the bootable file to be debugged. 

options is a list of the options given in Table 4.1. 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 
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4.3 Running the debugger 



Only one bootable file may be specified on the command line. 

If no arguments are given on the command line a help page is displayed giving the 
command syntax and a list of command line options. 

Command line parameters for programs being debugged interactively should not 
be entered on the debugger command line. The debugger will prompt for these 
parameters when the code being debugged is about to be started. 

Note: idebug is unique amongst the toolset tools in that, when invoked with 
command line options, Its driver program does not automatically reset (or analyze, 
as appropriate) the root transputer This is due to the diversity of hardware configu- 
rations where the appropriate sequence may not be obvious to the driver. Because 
of this, the task of selecting the appropriate iserver command is delegated to the 
user. 

Failure to supply the appropriate iserver reset (SR) or analyze (SA) options along 
with idebug command line options will result in iserver failing to boot idebug. 

Only when invoked with no command line options at all will idebug automatically 
reset the root transputer and display its own help page. 



Option 


Description 


A 


Assert 1NMOS subsystem Analyse. Directs the debugger to 
assert Analyse on the sub-networt< connected to the root 
processor. 

Required when using B004 type boards. 


AP 


A replacement for the A option when running programs on 
boards from certain vendors. Asserts Analyse on the network 
connected to the root processor 

Contact your supplier to see whether this option is applicable to 
your hardware. It does not apply to boards manufactured by 
INMOS. 


B tinknumber 


Interactive breakpoint debug a network that is connected to the 
root processor via link linknumber. idebug executes on the root 
processor. 

Must be accompanied by the iserver 'SR' option. 


c type 


Specify a processortype (e.g. T425) instead of a class (e.g. TA) 
for programs that have not been configured. 


D 


Dummy debugging session. Can be used for familiarization with 
the debugger or establishing memory mappings, 

Must be accompanied by the iserver ( SR' option. 


GXX 


Improves symbolic debugging support for C++ source code. 
Should be specified when debugging C++ programs. 
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Option 


Description 


I 


Display debugger version string. 

Must be accompanied by the iserver *SR r option. 


j ihexdigits 


Takes a hexadecimal digit sequence of up to 16 digits and repli- 
cates it throughout the data regions of a program (stack, static, 
heap and vectorspace as appropriate) when interactive debug- 
ging. The digit sequence must be preceded by a hash, '#', char- 
acter. 
Used when breakpoint debugging configured T426 programs. 


k #hexdigit$ 


As the J option but includes freespace. 

Used when interactive debugging non-configured T426 
programs. 


M linknumber 


Postmortem debug a previous interactive debugging session. 
idebug executes on the root processor. 

Must be accompanied by the iserver 'SA' option. 


N filename 


Postmortem debug a program from a network dump file file- 
name, created by idebug. The file is assumed to have the 
extension . dmp if none is specified. 
Must be accompanied by the iserver *sr' option. 


Q variable 


Specify environment variable used to specify the ITERM file. The 
default is "iterm". 


R filename 


Postmortem debug a program that uses the root transputer, fife- 
name is the file that contains the contents of the root processor 
(created by idump or isim). The file is assumed to have the 
extension .dmp if none is supplied. 


s 


Ignore subsystem signals when interactive debugging. 


T linknumber 


Postmortem debug a program that does not use the root 
processor, on a network that is connected to link iinknumber of 
the root processor, idebug executes on the root processor. 

Must be accompanied by the iserver 'SA' option. 


XQ 


Causes the debugger to request confirmation of the Quit 
command. 



Table 4.1 idebug command line options 



4.3.1 Toolset file types read by the debugger 

The debugger uses information within files produced by toolset tools in order to 
establish the hierarchy of components used to produce a bootable file. 

Table 4.2 provides a list of file types used by the debugger. The table covers all 
languages which the debugger supports (FORTRAN, C, and Occam), 
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File extension 


Description 


.f77 


FORTRAN source code file. 


.h77 


FORTRAN include file. 


,c 


C source code file. 


.h 


C include file. 


. occ 


occam source code file. 


.inc 


occam include file. 


.cfb 


Configuration data file. 


.pgra 


occam configuration data file. 


.btl 


Bootable file to be debugged. 


.btr 


ROM code file to be debugged. 


-clu 


Occam configuration object file. 


.lku 


Linked unit generated by linker. 


. tco 


Object file generated by compiler. 


.lib 


Library file. 


. dmp 


Root processor dump file (created by idvaap or isim) or 
network dump file (created by idebug). 



Table 4.2 File types read by debugger 

With the exception of a dump file which must have a . drop filename extension, the 
debuggerwill accept different extensions fora particular file type. (For example the 
extensions used by imakef such as . tah which can be used instead of , tco). 



4.3.2 Environment variables 

idebug requires three environment variables to be set up on the host system (in 
addition to those required to run the iserver and to build a bootable file). These 
are listed in table 4.3. Details of how to set up these variables can be found in the 
Delivery Manual that accompanies this release. 
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ITERM 


Contains the name of the file which defines key mappings for 
debuggersymbolic functions and some monitor page commands. 
The name of the environment variable may be over-ridden by 
using the 'Q' command line option. 


I DEBUGS I ZE 


Defines the amount of memory available on the root transputer 
board. This variable must be specified for idebug to work 
correctly (idebug requires at least 1 Mbyte of available root 
transputer memory: it is strongly recommended that 2 Mbytes or 
more be available). 


IBOARDSIZE 


The amount of memory available for the application program. 
Required for bootable single transputer programs (created from 
linked units using icollect with the T option and without the 
'M* option), where the memory size was not specified. 



Table 4.3 Environment variables used by idebug 



4.3.3 Program termination 

If the program terminates by issuing the 'terminate' command to the server, the 
following message is displayed: 

[Program has finished (after nnn seconds) - hit any key 
for monitor page} 

The debugger can be re-entered after server termination by pressing any key. The 
final state of the network can be examined using the full range of symbolic and 
Monitor page commands. 

The exit status returned by the program is displayed on the Monitor page. 

If the program contains independent processes which require no communication 
with the server then the debugger allows the program to be resumed. In this case 
the debugger displays the following warning message: 

[Warning: i server terminated by user program: use CTRL -A 
for monitor page] 



4.4 Post-mortem mode invocation 

To invoke the post-mortem debugger use the appropriate command from the 
following list Command lines are shown in both in UNIX and MS-DOS/VMS 
formats. 

Note: Commands are given for a B008 board wired subs {see section 4.7. 1). For 
the commands and command sequences to use on other board types see 
section 47.2, 
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4.4.1 Debugging T-mode programs - option 'T 1 

idebug bootablefile -t linknumber -sa 
idebug bootablefile /t linknumber /sa 

where: bootablefile is the program bootable file; 

linknumber is the number of the link of the root processor which is 
connected to the network. 

Use the 'T' option for programs that do not use the root transputer, that is those 
loaded by using iskip. The program is debugged from the program image that 
is resident in the memory of each transputer the information about the rest of the 
network is extracted down the root transputer link. This method provides the fastest 
post-mortem debugging because the root transputer memory image is not saved. 
However, the option does require an extra transputer on the network. The "t option 
should be accompanied by the 'SA' option to assert Analyse on the network. 



4.4.2 Debugging R-mode programs - option ( r' 

idebug bootablefile -r dumpfiie 
idebug bootablefile /r dumpfiie 

where: bootablefile is the program bootable file; 

dumpfiie is the root transputer memory dump file. 

Use the 'R' option for programs that use the root transputer in a network. The dump 
file is created by using idump, which produces a dump of the program image on 
the root transputer only; the debugger extracts information about other tra nsputers 
on the network (if applicable) via the root transputer's links. 



4.4.3 Debugging a network dump file - option 11' 

idebug bootablefile -n netfile -sr 
idebug bootablefile /n netfile /sr 

where: bootablefile is the program bootable file; 

netfile is a network dump file. 

Use the 'n' option to debug programs without access to the original network of 
transputers. This is effectively debugging off-line. The network dump file is gener- 
ated by the idebug Monitor page \W\ command. Note: this can only be used for 
programs that have not been debugged interactively. The *N' option should be 
accompanied by the iserver 'SR' option to reset the network. 
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4.4.4 Debugging a previous breakpoint session - option "to 1 

idebug bootablefile -m linknumber -aa 
idebug bootablefile /m linknumber /sa 

where: bootablefile is the program bootablefile; 

linknumber is the number of the link of the root processor which Is 
connected to the network. 

Use the 'if option to debug a previous breakpoint debuggi ng sessio n where either 
the network has crashed (error flag was set) or the host | BREAK | key was used 
to to terminate the debugger. This option is the same as the T option but informs 
the debugger the breakpoint runtime kernel is present. The to' option should be 
accompanied by the iserver 'SA' option to assert Analyse on the network. The 
same action may be achieved when using the debugger in interactive mode with 
a subsystem wired subs (see section 4.7.1) by use of the Monitor page \Y] 
command. 

Note: Symbolic functions and Monitor page commands that support breakpointing 
are absent in post-mortem mode. 

4.4.5 Re-invoking the debugger on single transputer programs 

For programs running on a single transputer only and debugged from a memory 
dump file the debugger can be re-invoked on the same dump file by passing the 
'SR' option to iserver from the idebug command line. This option is required to 
reset the transputer before loading the debugger program (the resetting is normally 
done by idump). 

4.4.6 Debugging boot from ROM programs 

Programs which are configured to boot from ROM and run in RAM may be 
debugged in post-mortem mode via a transputer link in a similar manner to that 
described in section 4.4.1. The debugger must be run on the root processor of the 
network (as specified to the configurer via the V option) which must be set to boot 
from link while debugging. 

idebug romcodefiie -t linknumber -sa 
idebug romcodefiie / 1 linknumber /sa 

where: romcodefiie is the .btr output file produced by icollect for use by 
ieprom; 

linknumber is the number of the link of the root processor which is 
connected to the network. 

4.5 Interactive mode invocation 

To run the debugger in interactive mode use one of the commands below. 
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Note: Commands are supplied for a BOOS board wired subs. For the commands 
to use on other board types see Table 4.4, 

idebug bootablefiie -b linknumber -sr 
idebug bootablefiie /b linknumber /sr 

where: bootablefiie is the program executable file; 

linknumber is the number of the root transputer link where the application 
network is connected. 

In interactive mode idebug loads the bootable file directly onto the network and 
sets up a runtime kernel and idebug virtual link system on each processor used 
by the program, i server is not required to load the program, but an extra 
processor is required to run the debugger; the program is in effect 'skip' loaded. 

When first invoked in interactive mode, the debugger immediately enters the 
Monitor page where the [¥] (Breakpoint Menu) command can be used to set 
breakpoints before the program is started. 

4.6 Function key mappings 

AH the debugger symbolic functions, and some Monitor page commands, are 
assigned to specific keys on the keyboard by the ITERM file (the file specified by 
the environment variable itebm). For the correct keys to use on your terminal 
consult the keyboard layouts provided in the Delivery Manual that accompanies 
this release. 

ITERM files are supplied with the release for terminals commonly used with your 
host system but may also be created to suit your own requirements. Details of the 
ITERM file and an example listing which illustrates the format can be found in 
appendix D. 

Key-mapped Monitor page commands are listed in section 4.9.7. A complete list 
of symbolic functions can be found in section 4.10. 

4.7 Debugging programs on INMOS boards 

On transputer boards the Analyse and Reset signals can be propagated from the 
root tra nsputer in two ways, and this influences the options that must be used whe n 
debugging programs. 

4.7.1 Subsystem wiring 

On transputer boards the subsystem signal is either propagated unchanged to all 
transputers on the network (known as wired down), or the signals are connected 
to the subsystem port (wired subs) from where they are controlled by the board's 
root processor. 
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On B004 boards and other boards where subsystem is wired in the same way 
Analyse must be asserted on the network before transputers can be accessed by 
the debugger from the root processor. However, if Analyse is asserted more than 
once the program will be corrupted in transputer memory. 

The wiring type can be identified by the hardware addresses of the three 
subsystem registers. On B004-type boards the addresses are as follows: 



Signal 


Hardware address 


Reset 


#00000000 


Analyse 


#00000004 


Error 


#00000000 



An example of a B0G4-type board is the IMS B404 TRAM. For details of the 
subsystem wiring on other boards consult the Datasheet or board specification. 

In addition, TRAM boards and B004 boards differ in the way the subsystem port 
is used. On TRAMs these subsystem signals are propagated to all transputers on 
the network, whereas on B004 boards the signals are not propagated at all. 

The sample program assert. occ illustrates resetting a B0Q4-type board. This 
program is supplied on the toolset examples directory. 



4.7.2 Debugging options to use with specific board types 

The conditions outlined above affect the commands that must be used when 
debugging T-mode and R-mode programs. Table 4.4 shows the command line 
options to use for different combinations of board type, subsystem wiring, and 
program mode. 

For further details about loading programs see the chapters on loading and debug- 
ging In the User Guide (chapters 7 and 9). 



4.7.3 Detecting the error flag in interactive mode 

In interactive mode the debugger detects that a processor has its error flag set by 
use of the subsystem services. If the hardware is not wired upto use the subsystem 
services then the debugger is unable to detect when an error flag is set; this may 
cause the debugger to hang for no apparent reason. On such networks the 
iserver 'SE' option should be used to detect when an error flag has been set. 
Note, however, that detection of a set errorflag will terminate the debugger without 
warning — the debugger can, however, be subsequently re-invoked in post- 
mortem mode. 

Note: When using the debugger in interactive mode, the hardware should be 
set-up to use the subsystem services if possible. 
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4.8 Debugging programs on non-INMOS boards 



Board 


Wiring 


Mode 


Command line(s) to use 


TRAM 


down 


T 


idebug program -h linknumber - sr -set -»t 


idebug program -m tinknumber -sa 


idebug program -t linknumber -sa 


R 


idump dumpfilesize 
idebug program -r dumpfile 


subs 


T 


idebug program -b linknumber -sr 


idebug program -m linknumber -sa 


idebug program -t linknumber -sa 


R 


idump dumpfilesize 
idebug program -r dumpfile 


B004 


down 


T 


idebug program -h linknumber -sr -set -»t 


idebug program -m linknumber -sa 


idebug program -t linknumber -sa 


R 


idump dumpftie size 
idebug program -r dumpfile 


subs 


T 


idebug program -b linknumber -a -sr 


idebug program -m linknumber -a -sa 


idebug program -t linknumber -a -sa 


R 


idump dumpfilesize 

idebug program -i dumpfile -a 


Command lines are given in UNIX format ('-' option switch character). For 
MS-DOS and VMS based toolsets use the '/' option switch character. 

The 'si' option may also be used on any command line to display activity 
information while the debugger is loading. 

Modes: R = program using the root transputer; T = program not using the root 
transputer, and debugged down a root transputer link. 

program is the program bootable file, 

t See section 4.7.3. 



Table 4.4 Commands to use on different board types 

4.8 Debugging programs on non-INMOS boards 

ff the hardware does not adhere to the INMOS subsystem convention then it is 
necessary to determine how the hardware is configured with respect to the 
subsystem and select the appropriate command line options. 

ft will probably be necessary to use the idebug command line 'S' option when 
breakpoint debugging in order to stop the debugger monitoring the subsystem 
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error status, and the iserver 'SE' option to determine when the error flag has 
been set. 

Note: Some non-INMOS boards use a specific subsystem convention which is 
supported by idebug, but which is different from the INMOS convention. To assert 
subsystem Analyse on such boards, use the 'AP' rather than the 'a 1 option. The 

board supplier should be able to say whether the 'ap' option is appropriate for their 
system. 

4.9 Monitor page commands 

This section lists and describes the debugger Monitor page commands. The 
commands are tabulated in alphabetical order for easy reference. Where a 
command invokes an option submenu the operation of each option in the submenu 
is described. 

Monitor page commands are also listed for easy reference in the Handbook that 
accompanies this release. 

4.9.1 Command format 

All Monitor page commands are either single letter commands or are invoked by 
a single function key press. Key mappings forthe few general commands that use 
function keys can be found in the Delivery Manual that accompanies this release. 

4.9.2 Specifying transputer addresses 

Many Monitor page commands require a memory address to be entered. Where 
there is a default value, this is displayed with the pr ompt. The default address is 
the last address specified or located to, and is used if | RETURN I is pressed without 
entering an address. 

Addresses can be specified in decimal or hexadecimal format. Hexadecimal 
nu mbers must be given as a sequence of hexadecimal digits preceded by th e char- 
acters '#', '$', or'%'. The'#' and '$' characters are used to prefix a full hexadecimal 
address. The '%' character adds mostneg int to the hexadecimal value using 
modulo arithmetic. This is useful when specifying transputer addresses which are 
signed and start at MOSTNEG INT, For example, %70 is interpreted as #80000070 
on a 32 bit transputer, and as #8070 on a 16 bit transputer. 

Address may also be specified relative to the iptr or Wptr (derived from the 
current wdeac) currently displayed in the monitor page. One of the following forms 
may be used: 

i+nnn or i-nnn: for addresses relative to Iptr — in this case nnn is a byte offset. 

w+nnn or *t-nnn: for addresses relative to Wptr — in this case nnn is a word offset. 

4.9.3 Scrolling the display 

Several commands mapped by the ITERM file (see below) may be used to scroll 
certain of the Monitor page displays. Cursor keys may also be used. 
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4.9.4 Editing functions 

The following string editing functions are available for on-screen editing of strinqs 
for certain commands: 



| start of line | Move the cursor to the beginning of the string. 

! Endofline"! Move the cursor to the end of the string. 

| delete line | Delete the string. 

3 Move the cursor left one character 

[►] Move the cursor right one character. 

[XI Replace the current string with the string used in the 
previous invocation of the command. 



dele ■ E] Delete the character to the left of the cursor 



| return | Enter the string. 

Note: | start of lin e], I endofline"! , I DELETE LINE] , and [delete] are 
mapped by the ITERM file to specific keys on the keyboard. Details of the key 
mappings on your terminal can be found in the Delivery Manual that accompanies 
this release. [X] will not be applicable to some commands. 

4.9.5 Commands mapped by ITERM 

Certain Monitor page commands are mapped to specific keys on the terminal by 
the ITERM file. Commands mapped in this way Include keys which are used to 
scroll the display (see below), commands which p roduce the s ame effect In both 
debugging modes, and the commands | top | , | retrace | , | RELOCATE 1 and 
1 resume | which invoke the corresponding symbolic mode functions. 

The keys to use for all Monitor page commands mapped by ITERM can be found 
by consulting the keyboard layouts supplied in the Delivery Manual. 

4.9.6 Summary of commands 



Key 


Meaning 


Description 


A* 


ASCII 


View a region of memory in ASCII. 


Bt* 


Breakpoint 


Display the Breakpoint menu enabling breakpoints to 
be set, cleared or listed. 


f = Interactive mode only. 

* = String editing functions available for these commands, see section 4.9.4. 
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Key 


Meaning 


Description 


C 


Compare 


Compare the code on the network with the code that 
should be there to ensure that the code has not been 
corrupted. 


D* 


Disassemble 


Display the transputer instructions at a specified area 
of memory. 


E 


Next Error 


Switch the cunent display information to that of the 
next processor in the network which has halted with its 
error flag set. 


F* 


Select file 


Select a source file for symbolic display using the file- 
name of the object file produced for it. 


G 


Goto process 


Goto symbolic debugging for a particular process. 


H* 


Hex 


View a region of memory ':?. hexadecimal 


1* 


Inspect 


View a region of memory in a symbolic type. Types are 
expressed as standard occam types. 


Jt* 


Jump 


Start or resume the application program. 


K 


Processor 
names 


Display the names and types of all processors in the 
network. 


L 


Links 


Display instruction pointers and process descriptors 
for the processes currently waiting for input or output 
on a transputer link, or for a signal on the Event pin. 


M 


Memory map 


Display the memory map of the current processor. 


N* 


Network dump 


Copy the entire state of the transputer network Into a 
'network dump' file in order to allow continued (off-line) 
debugging at a later date. 


0* 


Specify process 


Resume the source level symbolic features of the 
debugger for a particular process. 


P* 


Processor 


Switch the current display information to that of 
another processor 


Q 


Quit 


Leave the debugger and return to the host operating 
system. 


R 


Run queues 


Display instruction pointers and process descriptors of 
the processes on either the high or low priority active 
process queue. 


St 


Show messages 


Display the Messages menu enabling the default 
actions of the debugger to debug support functions to 
be changed. 


f = Interactive mode only. 

* = String editing functions available for these commands, see section 4.9.4. 
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4,8 Debugging programs on non-INMOS boards 



Key 


Meaning 


Description 


T 


Timer queues 


Display instruction pointers, the process descriptors 
and the wake-up times of the processes on either the 
high or low priority timer queue. 


ut 


Update 


Update the monitor page display to reflect the current 
state of the processor. 


V 


Process names 


Display the memory map of processes on the current 
processor. 


wt* 


Write 


Write to any portion of memory in a symbolic type. 
Types are expressed as standard occam types. 


X 


Exit 


Return to symbolic mode. 


Yt 


Postmortem 


Change an interactive breakpoint debugging session 
into a post-mortem debug session. 


z 


Virtual links 


Display instruction pointers and process descriptors 
for processes waiting on the configurer's software 
virtual links. 


? 


Help 


Display help information. 


f = Interactive mode only. 

* = String editing functions available for these commands, see section 4.9.4. 



4.97 Symbolic-type commands 

| HELP | Display help information. 

Re-draw the screen. 

Switch to symbolic mode and perform symbolic relocate. 
resume | Restart a process stopped at a breakpoint. 

RETRACE 1 Switch to symbolic mode and perform symbolic retrace. 



REFRESH 



RELOCATE 



TOP | 



Locate to the last instruction executed on the current 
processor. 



Key bindings for these commands on specific terminal types can be found in the 
rear of the Delivery Manual. 



4.9.8 Scroll keys 



LINEUP 



Scroll the currently displayed memory, disassembly, queue, 
or list. 
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line down] Scroll the currently displayed memory, disassembly, queue, 

or list. 



Scroll the currently displayed memory, disassembly, queue, 
or list 

page down") Scroll the currently displayed memory, disassembly, queue, 
or list. 



top OF file | Go to the top of the currently displayed processor name 
list, or software virtual link list. 



| END OF FILE | Go to the end of the currently displayed processor name 
list, or software virtual link list. 

[XI Scroll the currently displayed memory, disassembly, queue, 

or list. 

|"T"| Scroll the currently displayed memory, disassembly, queue, 

or list, 

\~4] Scroll the currently displayed processor left. 

[►H Scroll the currently displayed processor right. 

Key bindings for these commands on specific terminal types can be found In the 
rear of the Delivery Manual. 

4.9.9 Monitor page command descriptions 

[A] ASCII 

This command displays a segment of transputer memory in ASCII format, 
starting at a specific address. If no address is given the last specified 
address is used. Specify a start address after the prompt: 

Start address (§hhhhhhhh) ? 



Either press | RETURN ] to accept the default (last specified) address, or 
enter the desired address. The address can be entered as a decimal 
number, a hexadecimal number preceded by '#', or the short form 

%h...ti. 

The memory is displayed in blocks of 16 rows of 32 ASCII bytes, each row 
preceded by an absolute address in hexadecimal. Bytes are ordered from 
left to right in each row. Unprintable characters are substituted by a full 
stop. 

The scroll keys (section 4.9.7) can be used to scroll the display. 
72 TDS 367 01 March 1 993 
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|~B~[ Breakpoint menu (interactive mode only) 

This command invokes the Breakpoint Menu: 

Breakpoint Menu 
S - Set a breakpoint on this processor 
T - Toggle a breakpoint on this processor 
C - Clear a numbered breakpoint 
A - Clear all breakpoints on all processors 
B - Clear all breakpoints on this processor 
E - Set a breakpoint at all entries this processor 
G - Set a breakpoint at all entries all processors 
M - Set a breakpoint at all main () this processor 
L - List all breakpoints and hits 

P - List all breakpoints and hits on this processor 
Q - Quit this option 

Breakpoint option (A,B,C,E,G f L,M,P,Q,S,T) ? 

Options are selected by entering one of th e single le tter commands, A 
selected option can be cancelled by pressing ; return | with no typed input 
when it prompts for an address or a breakpoint number. 

The 'E' and 'G' options, which set breakpoints at the entry point of all config- 
uration level processes, are mainly for use with Occam programs where 
the entry point of the program is the start of the top-level process. For non- 
configured occam programs the entry point is the first procedure called 
when the program starts. For configured Occam programs the entry point 
is the configuration level code. 

The 'm' option is intended for languages which have run-time support and 
a known entry point to the application code (such as main { ) in C, or the 
FORTRAN main program). This option sets a breakpoint at all the program 
entry points on the current processor. 

Note: for processors which do not have hardware breakpoint support the 
debugger will not set breakpoints in high priority configuration level 
processes when the 'E\ 'G' or ( M* options are used. 

Breakpoints are assigned a unique number which must be used with the 
'C option. Numbers are given on the List Breakpoints displays. 

In addition, the List Breakpoint displays provide information about the 
processor the breakpoint has been placed on (Proc:), the address of the 
breakpoint (Addr:}, the number of times the breakpoint has occurred 
(Hits :) and for breakpoints set in symbolic mode the filename and line 
number they correspond to. For example: 

4) Proc: 0, Addr: #8Q00408E, "facs.c":201 
Hits: 3 
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This display means that breakpoint number 4 on processor at address 
#8000408E (which corresponds to line number 201 of the file *f acs . c") 
has been hit three times. 

Note: Only breakpoints which are set in symbolic mode (at the beginning 
of a statement) are properly supported. Setting breakpoints at arbitrary 
addresses using the 's' option may cause incorrect execution of the 
program. 

Note: Breakpoints should not be set in high priority processes on proces- 
sors without hardware breakpoint support (M212, T212, T222, T414, and 
T800). The E, G and M options will not set a breakpoint in a high priority 
(configuration level) process on these processors. 

[c] Compare memory 

This option compares the code actually in memory on the network with the 
code that was loaded, to check that memory has not become corrupted. 

Note: This option treats breakpoints as corrupted code. 

The following menu is displayed: 

Compare memory 
Number of processors in network is : n 

A - Check all network processors for discrepancies 

B - Check this processor for discrepancies 

C - Compare memory of this processor on screen 

D - Find first error on this processor 

Q - Quit this option 

Compare memory option (A,B,C,D,Q) ? 

Type one of the options a, b, C, D, or Q. Option 'Q' returns to the Monitor 
page. 

Checking the whole network - option A 

Option 'A' checks all the processors in the network and displays a summary 
of the discrepancies found. 

If there are no errors the following message is displayed: 

Checked all processorrrs in network OK 

If any errors are detected the number of errors is given along with the 
address of the first error found and the name of the processor on which it 
occurred. 
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Checking a single processor • option B 

Option 'B' checks just the current processor. In all other respects it is similar 
to option 'A'. 

Compare memory on screen - option C 

Option 'C displays the actual and expected code for each address in the 
program code area of the current processor Discrepancies are marked 
with an asterisk ('*'). 

Memory is checke d in blocks of 128 bytes. At the end of each block, type 
either C Q' to quit, or | space | to read and display the next block. 

The format of the display is similar to the following example: 

Processor Code Correct Code 

#800001234 : 0011223344556677 7766554433221100 * 

#80000123C : 0011223344556677 0011223344556677 

#800001244 : 0011223344556677 7766554433221100 * 

#8000012AC : AABBCCDDEEffOOll AABBCCDDEEffOOll 

Press [DOWN] to scroll memory, [SPACE] for next err 
or, or Q to quit : 

Pressing [SPACE | automatically invokes option 'D' - Find first 
error . . . (see below). 

Find first error - option D 

Option 'D' searches the current processor's memory for the first occurrence 
of a discrepancy, if a discrepancy is found the display is the same as in 
option 'C above, and the memory can be checked and displayed as in 
'Compare memory on screen 1 . 

| D | Disassemble memory 

The Disassemble command disassembles memory into transputer instruc- 
tions. Specify an address at which to start disassembly after the prompt: 

Start address ithhhhhhhh) ? 

Either press ; RETURN | to accept the default address, or enter the desired 
address. The address can be entered as a decimal number, a hexadecimal 
number preceded by '#', or the short form l %h... h\ 

The memory is displayed in batches of sixteen transputer instructions, 
starting with the instruction at the specified address. If the specified 
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address is within an instruction, the disassembly begins at the start of that 
instruction. Where the preceding code is data ending with a transputer 
"pf ix' or 'nf ix' instruction, disassembly begins at the start of the pf ix or 
nf ix code. 

Each instruction is displayed on a single line preceded by the address 
corresponding to the first byte of the instruction. The disassembly is a direct 
translation of memory contents into instructions; it neither inserts labels, 
nor provides symbolic operands. 

The scroll keys (section 4.9.7) can be used to scroll the display. 

|~E~| Next Error 

Next Error searches forward through the network for the next processor 
which has both its error and halt-on-error flags set. Processors are 
searched in the same order as they are Listed by the 'K' command, starting 
from the current processor and wrapping round. If a processor is found with 
both flags set the display is changed to the new processor as If the ( P' option 
had been used. Press | top | to display the source line which caused the 
error. 

If there is only one processor in the network then a message to this effect 
is displayed. 

fF~| Select source file 

This command enables a program source file to be displayed within the 
symbolic debugging environment for a particular processor. This allows 
breakpoints to be set in modules which have not yet been reached in the 
program's execution. (Source which has not yet been executed cannot be 
displayed using the '0' or 'G' options because the iptr and wdesc 
addresses are not yet known.) 

When the source file is first displayed, the cursor is placed on the first 
source code line which generates object code. If the start of the source file 
contains an include file it is possible for the debugg er to locate th is instead. 
In order to locate the intended source file, use the 1 exit file \ key to exit 
the include file. 

The select source file command may also be used to browse source files 
rather like the | CHANGE file] symbolic function. However, unlike 
I CHANGE FILE I it allows some of the symbolic debugging operations to be 



used. 

Note: Editing keys may be used with this command to provide a simple 
history mechanism (see section 4.9.4). 

For mixed language programs, the behavior of this command will differ 
depending on whether icconf or the occam configurer occonf has 
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been used to configure the program, {icconf is supplied with FORTRAN 
and ANSI C toolsets, occonf with occam toolsets.) 

The differences in the behavior are described below: 

Behavior of command when no configurer or icconf is used 

If a processor has been configured to contain more than one process, this 
option first prompts for the process number corresponding to the source 
code: 

Select process number (0 - N) ? 

The range of numbers displayed in brackets are process numbers 
assigned by the debugger to different processes on the processor The 
process numbers assigned to process names by the debugger can be 
determined by using the Monitor page Process Name (V) option before 
invoking the 'F' command. 

Once a valid process number has been supplied (if applicable), the 
debugger prompts forthe filename of the compiled object module. The full 
object filename (including extension — conventionally .tco) must be 
supplied. 

Object module filename ? 

The object filename must be specified because the debugger extracts the 
source code filename from the debug information in the compiled object 
file. 

Note: Editing keys may be used with this command to provide a simple 
history mechanism (see section 4.9.4). At each prompt this command may 
be aborted by pressing [RETURN | with no typed input. 

Behavior of command when occonf is used 

The debugger first prompts for the filename of a linked object module. The 
full linked filename (including extension — conventionally . lku) must be 
supplied. 

Linked unit filename ? 

The linked filename must be specified because the debugger needs to 
know which linked unit (incorporated by a configurer #use directive) 
contains the object code from the source file to be displayed. 

The debugger then prompts for the filename of a compiled object module 
contained within the selected linked unit. The full object filename (including 
extension — conventionally , tco) must be supplied. 

Object module filename ? 
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The object module filename must be specified because the debugger 
extracts the source code filename from the debug information in the 
compiled object file. 

At each prompt this command may be aborted by pressing |_ return | with 
no typed input 

\~g] Go to process 

This command locates to the source code for any process which is 
currently shown on the screen. Any process displayed by using the |~i~| , 
IT] , [R], [T], or|T] commands may be selected. 

The cursor is positioned next to the Iptr value and permitted responses 
are listed on the screen, as follows: 

Goto process - use [CURSOR] then [RETURN] , or to 
F, (I)ptr, (L)o or (Q)uit 

To select a process and display the source code, move the cursor to a 
displayed iptr value and press | return | , or use one of the following 
short-cuts: 

• The [T] option locates to the current process (the process corre- 
sponding to the displayed Iptr and Wdesc values), 

• If currently in high priority, the [V] option can be used to locate to 
the interrupted low priority process (the process corresponding to 
the displayed IptrlntSave and WdesdntSave values). 

• The hex numbers [jf] — [T] will locate to the process corre- 
sponding to one of the 16 lines displayed on the right hand side 
of the Monitor page (the entries in the timer or run queues, or 
processes waiting on links). 

Type 'Q\ | finish | , or | refresh | to abort this command. 

[H] Hex 

The Hex command displays memory in hexadecimal. Specify the start 
address after the prompt: 

Start address tfhhhhhhhh) ? 

Press | return | to accept the default address, or enter the desired 
address. The address can be entered as a decimal number, a hexadecimal 
number preceded by '#', or the short form '%iu . . ti. If the specified start 
address is within a word, the start address is aligned to the start of that 
word. 
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The memory is displayed as rows of words in hexadecimal format. Each 
row contains four or eight words, depending on transputer word length. 
Words are displayed in hexadecimal (four or eight hexadecimal digits 
depending on word length), most significant byte first 

For a four byte per word processor the sequence of bytes in a single row 
would be: 

3 2 10 7 6 5 4 11 10 9 8 15 14 13 12 

For a two byte per word processor, the ordering would be: 

10 3 2 5 4 7 6 9 8 11 10 13 12 15 14 

Words are ordered left to right in the row starting from the lowest address. 
The word specified by the start address is the top leftmost word of the 
display. 

The address at the start of each line is an absolute address displayed in 
hexadecimal format. 

The scroll keys (section 4.9.7) can be used to scroll the display. 

| I | Inspect memory 

The Inspect command can be used to inspect the contents of an entire 
array. Specify a start address after the prompt: 

Start address tfhhhhhhhh) ? 



Either press | return ] to accept the default address, or enter the desired 
address. The address can be entered as a decimal number, a hexadecimal 
number preceded by '#', or the short form %h . . . ti. 

When a start address has been given, the following prompt is displayed: 

Typed Memory Dump 

- ASCII 

1 - INT 

2 - BYTE 

3 - BOOL 

4 - INT16 

5 - INT32 

6 - INT64 

7 - REAL32 

8 - REAL64 

9 - CHAN 

Q - Quit this option 

Which occam type (1 - INT) ? 
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m 



Give the number corresponding to the type of data to be displayed, press 
| RETURN | to accept the default type or enter Q to quit this option. 

The types correspond to formal Occam types as defined in the occam 2 
Reference Manual, occam equivalences of C and FORTRAN types are 
listed in table 4.5. 



c 


FORTRAN 


occam 


int 


INTEGER 


INT 


char 
unsigned char 


CHARACTER 


BYTE 




LOGICAL 


BOOL 


short 
signed short 


INTEGER*2 


INT16 


long 

signed long 


INTEGER* 4 


INT32 


float 


REAL 
REALM 


REAL32 


double 
long double 


DOUBLE PRECISION 
REAL'S 


REAL64 



Table 4,5 Type equivalents for Inspect command 

ASCII arrays are displayed in the format used by the Monitor page 
command [A], Other types are displayed both in their normal representa- 
tion and hexadecimal format. 

The memory is displayed as sixteen rows of data. The address at the start 
of each line is an absolute address displayed as a hexadecimal number. 
The element specified by the start address is on the top row of the display. 

Start addresses are aligned to the nearest valid boundary for the type, that 
is; byte and BOOL to the nearest byte; INT16 to the nearest even 
byte; INT, INT32, INT64, REAL32, REAL64, and Chan to the nearest 
word. 

The scroll keys (section 4.97) can be used to scroll the display. 

Jump into and run program 

This command starts up a program from the Monitor page, or restarts a 
process which has encountered a breakpoint or has been stopped by one 
of the debug support functions (for details of these functions see the 
appropriate Language and Libraries Reference Manual). 

Starting a program 

When starting a program the debugger converts {patches) the configura- 
tion external channels (those assigned to links) for each processor into 
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virtual channels for use with the debugging kernel This action is indicated 
by an activity indicator 

When the patching is complete the debugger prompts for a command line 
for the program: 

Command line: 

Simply press | RETURN | if the program does not require any command line 
parameters. The program will then start running. 



Resuming from a breakpoint 

When jumping into and resuming a program from a breakpoint, in the 
monitor page, the following menu is displayed: 

Jump into Application 

R - Resume process stopped at a breakpoint 
O - Resume monitoring of network 

(abandon process stopped at a breakpoint) 
J - Restart process at a different location 
Q - Quit this option 

Which option (J,G,Q,R) ? 

Note: the [ RESUME j key can be used as an alternative to using this 
command with the R option. 



Resuming from debug support functions 

When resuming from one of the debug support functions, the following 
submenu is displayed: 

Jump into Application 

- Resume monitoring of network 

(abandon process stopped at a program error) 
J - Restart process at a different location 
Q - Quit this option 

Which option (J,0,Q) ? 



Jump options 

The four Jump options are described in the following table: 
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Option 


Description 


R 


Restarts the process that encountered the breakpoint. 





Ignores the stopped process and resumes monitoring the 
network for other process activity. 

Note: When a process has stopped, other processes 
continue to run until they either encounter a breakpoint or 
program error (i.e. one of the debugging support functions), 
or become dependent on the stopped process. 

Note: Using this option for a process stopped on a breakpoint 
removes the process forever. 


J 


Restarts the process from a different location. Only use this 
option if you are confident that the program can be resumed 
from the new location; resumption from most locations will 
corrupt the program. 


Q 


Quits the Jump sub-menu. 



Editing keys 

Editing keys may be used with this command when entering the command 
line parameters starting the program, see section 4.9.4. 

|~K"] Processor names 

This command displays the internal processor numbers corresponding to 
processor names used in the configuration description and the corre- 
sponding processor type. Processor numbers must be given when 
selecting specific processors for display. 

The scroll keys (section 4.9.7) can be used to scroll the display. 

Note: The debugger displays only the first 19 characters of the processor 
name, If this Is a problem then names should be made unique within the 
first 19 characters. 

rn Links 

The Links command displays the instruction pointer, workspace descriptor, 
and priority of the processes waiting for communication on the links, orfor 
a signal on the Event pin. If no process is waiting, the link is described as 
'Empty*. Link connections on the processor, and the link from which the 
processor was booted, are also displayed. 

If a processor uses software virtual links then the title line of the data 
displayed appears as: 

Link Information (virtual links present) 
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This is to warn that the link state information may be for software virtual 
processes which cannot be located to in the normal manner. In this case 
it is more useful to use the Monitor pagejT] command to display the soft- 
ware virtual links instead. 

For configured programs, the debugger checks that the link the root 
processor has been booted from matches that expected by the configurer. 
It it does not, the following message is displayed: 

Booted from link n < Should be link m 1 ! ! > 

The format of the display is similar to the following: 



Link 
Link 
Link 
Link 
Link 
Link 
Link 
Link 
Event 



#80000256 Wdesc: #80000091 (Lo) 



Link Information 
out Empty 
out Empty 
out Iptr; 
out Empty 
in Empty 
in Empty 
in Iptr : 
in Iptr : 
in Empty 



#80000321 Wdesc: 
#80000554 Wdesc: 



#80000125 
#80000170 



(Lo) 
(Hi) 



1, Link 1 



Link connected to Host 
Link 1 not connected 
Link 2 connected to Processor 
Link 3 connected to Edge 

Booted from link 

[~M~| Memory map 



The Memory map command displays the memory map of the current 
processor along with the mode that idebug is currently in. The mode may 
be one of: 



Mode 


Description 


Interactive Mode 


Interactive breakpoint debug- 
ging session 


Postmortem Interactive Mode 


Postmortem debugging session 
of a previous interactive debug- 
ging session. 


Postmortem Mode 


Postmortem debugging session 
either down a transputer link or 
from a dump file. 


Dummy Session 


Dummy debugging session 
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The display includes the address ranges of on-chip RAM, program code, 
configuration code, stack (workspace) and vectorspace, the sizes of each 
component in bytes rounded up to the nearest 1K bytes, total memory 
usage, and the address of MemStart (the first free location after the RAM 
reserved for the processor's own use). 

Also displayed is the total memory usage. Total memory usage indicates 
the amount of memory used by a user program. Note that this may include 
a region of memory at the beginning of freespace; this area is used for 
configuration code before execution of a user program starts (this memory 
may be safely overwritten by the user program because the configuration 
code finishes executing before the user code starts). 

The minimum memory size specified to the configurer or the collector, or 
as defined in iboardsize as appropriate, must be at least as large as the 
total memory usage for each processor. 

Also displayed is the maximum number of processors that can be accom- 
modated by the debugger's buffer space. This will depend on the amount 
of memory on the root processor, indicated to the debugger by the host 
environment variable IDEBOGSIZE. 

The address of MemStart is the value actually found on the transputer In 
the network. If this does not correspond to that expected by the configura- 
tion description, for example if a T414 was found when a T805 was 
expected, the following message is displayed: 

MemStart: #80000048 (T414)? 

MemStart should be: #80000070 (T805) «!» 

If an incorrect MemStart is detected the symbolic functions may not work 
correctly. In this case the program should be rebuilt for the correct 
processor types before re-invoking the debugger. 

|~N~| Network dump 

The Network dump command saves the state of the transputer networkfor 
later analysis. If the debugger is terminated without creating a network 
dump file, debugging cannot continue from the same point without re-run- 
ning the program. This is because the debugger itself overwrites parts of 
the memory on each transputer in the network. 

Note: This command cannot be used in interactive mode (idebug 
command line option ( B P ) or when post-mortem debugging a breakpoint 
session (idebug command line option ft'). 

Once a network dump file has been created, debugging can continue from 
the dump file, and the debugger does not need to be connected to the 
target network. 
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Before the dump file is created, the debugger calculates the disk space 
required, and requests confirmation. The size of the file depends on hov: 
much of each processor's memory is actually used in running the program, 
and is displayed as follows: 

Create network dump file 
Number of processors to dump : .2 
File size excluding Freespace : 112604 bytes 
File size including Free space : 2057308 bytes 

Continue with network dump (Y,N) ? 

To continue with the network dump, type Y. 

The debugger will then ask whether to include freespace in the dump file 
(this is not normally required for configured programs). 

Do you wish to include Freespace (Y,N) ? 

Type *r or If as appropriate and specify a filename after the prompt: 

Filename ("network-drnp" or "QUIT") ? 

Press | return | to accept the default filename, enter a filename (any 
extension will be replaced by ' . dmp') ( or type 'QUIT' (uppercase) to exit 

If the file already exists, confirmation is asked for 

File "network. drap" already exists 
Overwrite it (Y,N) ? 

If *K' is entered then a new filename is asked for 

While the dumpfile is being written, a message is displayed at the terminal. 
For example: 

Dumping network to file "network , dmp" . . . 

Processor 1 (T800) 

Memory to dump : 10456 bytes . . . 

' o] Specify process 

This command returns to symbolic debugging, either at the same source 
line, or at another location. It can be used to locate to any source line, 
whether or not a process is waiting or executing there. To ensure the 
debugger locates to a valid process, it is better to use the 's J command. 

To return to symbolic debugging, the debugger requires values for iptr 
and Wdesc. Specify Iptr after the prompt: 

Iptr tfhhhhhhhh) ? 
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The default displayed in parentheses is the last tine located to on this 
processor, or the address of the last Instruction executed. Either press 
["return") to accept the default address, or enter the desired address. The 
address can be entered as a decimal number, a hexadecimal number 
preceded by '#', or the short form %h. . .h'. 

Useful process addresses can be determined using the [T], QT], or \T] 
commands to display processes. These processes can, however, be more 
easily located by using the [g] command. The value of the saved low 
priority iptr can also be used. 

If the Iptr is not within the program body, the debugger indicates the type 
of code to which it corresponds. 

After the iptr has been entered the debugger prompts for the value of the 
process descriptor 

Wdesc tfhhhhhhhh) ? 

If a displayed Iptr was specified, Its corresponding wdesc is offered as 
a default. Press | return | to accept the default, or specify a value in the 
same format as the iptr. 

If no symbolic features otherthan a single 'locate 1 are required, then Wdesc 
is not needed and the default can be accepted. 

If an invalid Wdesc is given, most of the symbolic features wiEl not work, or 
will display incorrect values. However, the values of scalar constants and 
some other symbols can still be determined. 

Any attempt to inspect or modify variables or channels, orto backtrace, will 
give one of the following messages: 

Wdesc is invalid - Cannot backtrace 

Wdesc is invalid - Cannot Inspect variables 

Wdesc is invalid - Cannot Modify variables 

Wdesc is invalid - Cannot auto backtrace out of library 

Once the Iptr and Wdesc have been supplied, the debugger displays the 
source code at the required location, and the full range of symbolic features 
are available. 

|~p~| Change processor 

This command changes to a different processor in the network. Specify the 
processor number after the prompt: 

New processor number (0 - n) ? 

To determine the mapping between the processor number and the 
processor name used in the configuration file, use the 'K' command. If the 
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processor exists the display is changed to provide information about the 
specified processor. If the new processor's word length is different from 
that of the previous processor, the start address is reset to the bottom of 
memory. If the processor is not in the configuration, the following message 
is displayed: 

Error : That processor number does not exist 



To abort the command press ["return"! with no input. 

If there is only one processor in the network, an appropriate message is 
displayed. 

The scroll keys (section 4.9.7) can be used to change the displayed 
processor. The sequence of processors is the same as that displayed by 
the 'K 1 command. 



["51 Quit 

This command quits the debugger and returns to the operating system. 
Once quit, the debugger cannot be used to debug the same program 
without reloading the program unless a 'network dump' file has been 
created. This is because using the debugger overwrites some of the 
contents of the network. 

If the command line option XQ has been used the debugger will ask for 
confirmation before quitting. 

R ] Run queues 

This command displays iptrs and wdescs for processes waiting on the 
processor's active process queues. If both high and low priority front 
process queues are empty, the following message is displayed: 

Both process queues are empty 

If neither queue is empty, the debugger ask which queue is to be displayed: 

High or low priority process queue ? (H,L) 

Type 'R' or 1/ as required. If only one queue is empty, the debugger displays 
the non-empty queue. 

The screen display is paged. The scroll keys (section 4.9.7) can be used 
to scroll the display. 

Note: In interactive mode this command may show the details of a process 
more than once. The string '< ! >' next to the queue heading serves as a 
reminder that this may occur. 

Processes which belong to the debugging kernel are also displayed and 
identified with the string ' (Runtime kernel)'. 
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fs~l Show debugging messages 

This command is used to enable and disable debugging messages and 
prompts. It invokes the following submenu: 

Show Messages Menu 

3 -- Show message for breakpoints : ON 

D — Show debug messages : ON 

E — Show message for program errors : ON 
Q -- Quit this option 

which option (B,D,E r Q) ? 

Options B and z control the display of prompts when a breakpoint or 
program error (i.e. one of the debug support library functions 
debug_assert() and debug_stop(), etc.) is encountered. Disabling 
these options ensures that the debugger is entered on a breakpoi nt or error 
without requesting confirmation. 

Option D controls the display of debugging messages inserted with the 
Library functions debug_mes sage ( ) , etc. 

~ Timer queues 

This command displays Iptrs, wdescs, and wake-up times for processes 
waiting on the processor's timer queues. Prompts and displays are similar 
to those for the Run queues command. 

pj] Update registers 

This command updates the clock and status display (e.g. run queues, links) 
for the current processor. It enables the activity of other processes to be 
monitored while one process is stopped at a breakpoint or error. 

|~v~| Process memory map 

This command provides details on each process resident on a processor. 
This consists of user processes, and configuration processes for virtual 
channels {if applicable: their names begin with a V); it does not include the 
debugging kernel used by the debugger when interactive breakpoint 
debugging (this information is shown by the Memory Map option). 

A process is assigned a number by the debugger in order to identify the 
process when using certain other monitor page options. In addition to the 
process number, the following details are provided: the name of the 
process, the priority the process starts in, and the process stack and code 
areas. Note that for non-configured C programs, the stack area displayed 
is not that used by the program (the actual stack used is provided by the 
freespace area). 
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An example output for two configured processes is shown below: 

Process Memory Hap 



Process 
Initially : 
Stack : 


; "occafl^process" 

; High priority 

; #80005000 - #80005023 


Code : 


: #8000A038 - #8000A04B 


Process 1 ; 

Initially ; 

Stack : 


; "c_process" 

; Low priority 

: #80005024 - #8000A037 


Code : 


: #8000A04C - #8000D73B 



Note: The debugger displays only the first 19 characters of the process 
name. If this is a problem then names should be made unique within the 
first 19 characters. 

Note: Processes placed on a processor to provide software virtual links 
have names starting with '%'. 

[W] Write to memory 

This command writes a value to a specified address. Values must be speci- 
fied in the current type (the type used in the previous Monitor page inspect 
command), or the Occam type INT if the type was a CHAN or the Disas- 
semble or Hex options have been used after an Inspect. 

\Y\ Exit 

This command returns to symbolic mode and locates to the current 
address. 

HH Enter post-mortem debugging 

This command allows the debugger to be switched into post-mortem mode 
when the program crashes (a process sets the errorflag on any processor). 
Halted processors prevent the breakpoint debugger from accessing the 
network correctly and debugging must continue in post-mortem mode. It 
has the same effect as re-invoking the debugger with the command line W 
option. 

If the program has not already started, then the debugger prompts for 
confirmation: 

The program has not started * are you sure (Y,N) ? 

If the program has not crashed, the debugger prompts for confirmation: 

The program has not crashed - are you sure (Y,N) ? 

If checking of the subsystem error status is disabled (with the command 
line 's 1 option), then the prompt is: 

Unable to detect if the program has crashed - are y 
ou sure (Y,N) ? 
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Typing 'Y' continues the operation, typing If aborts it 

This command will only work if the subsystem is wired subs (see section 
4.7.1). For a subsystem wired down, it is necessary to quit and restart the 
debugger using the Monitor page f tf command line option (instead of the 
previous breakpoint command line 'b' option). 

Note: State information for a process that has stopped (on breakpoint or 
error) will be lost when switching from breakpoint to post-mortem mode. If 
the information is important it should be noted before switching modes. 

|~z~| Display software virtual links 

This command displays instruction pointers and process descriptors for the 
processes currently waiting on software virtual links placed onto a processor by the 
configuer. All of the virtual output links (displayed as Vout N) are displayed 
followed by all of the virtual input links (displayed as vin N). 

The scroll keys {section 4.9.7) can be used to scroll the display. 

In order to establish the mapping of user channels onto software virtual links on 
a particular processor, you should use the configurer information 'I' option when 
configuring. 

Note: all low priority user processes using software virtual links will be promoted 
temporarily to high priority when they communicate. The debugger cannot tell if 
they were originally at high or at low priority. If you need to specify a low priority 
wdesc then use the displayed value with the least significant bit set (e.g. %l23d 
becomes %1235). 



4.9.10 Symbolic-type commands 

| TOP | 

This command is used to display the source corresponding to the last 
instruction to be executed on the current processor. It is the same as typing 
'G', then 'I 1 (or 'G', then [ RETURN | ). 



RELOCATE I 



This command returns to symbolic mode and performs a symbolic 
| relocate | . ft cannot be used if the processor has been changed at the 
Monitor page. 

| RETRACE | 

This command returns to symbolic mode and performs a symbolic 
| retrace 1 . It cannot be used if the processor has been changed at the 
Monitor page. 
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| RESUME J 

This command resumes a process stopped at a breakpoint in a similar 
manner using the | resume ] command when in symbolic mode. It is a 
shorthand equivalent to using the J command and selecting the r option 
to resume a process stopped at a breakpoint from the monitor page. 



ED 



HELP | 



These commands display a summary of the commands available at the 
Monitor page. 



REFRESH 



This command refreshes the screen. 



4.1 Symbotic functions 

Symbolic debugging allows high level language programs to be debugged from the 
identifiers used in the source code. Symbolic identifiers are the names given in the 
program to variables, constants, channels, and functions. 

Symbolic functions are invoked using keyboard function keys. Keyboard layouts 
that show the key bindings for common terminal types can be found in the Delivery 
Manual that accompanies the release. The symbolic functions are summarized 
alphabetically below. Each description includes a reference to the page where the 
command function is described in more detail. 

Note: t = Functions only available in interactive mode. 



backtrace] Locate to the calling function or procedure [page 112]. 



end of FtLE~| Go to the last line in the file [page 113]. 



CHANGE FtLE~| Display a different source file [page 113]. 



channel ] Locate to the process waiting on a channel [page 110]. 

continue from | * Restart a stopped process from the current line [page 111]. 
enter file"] Change to an included source file [page 11 3]. 



EXIT FILE | Return to the enclosing source file [page 113]. 



| FINISH | Quit the debugger [page 114]. 

| getaddress"! Display the location of a source line in memory [page 113]. 
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GOTO LINE 



HELP 



INFO 



INSPECT 



INTERRUPT 



MODIFY ! 



MONITOR 



RELOCATE 



| RESUME 



RETRACE 



SEARCH 



| TOGGLE BREAK" 
I TOGGLE HEX [ 



Go to a specific line in the file [page 113]. 

Display a summary of commonly used symbolic functions 
[page 113]. 

Display process information (e.g. instruction pointer, 
process descriptor, process name) [page 110]. 

Display the type and value of a source code symbol 
[page 109]. 

Force the debugger into the Monitor page without stopping 
the program [page 111]. 

Change the value of a variable in memory [page 111]. 

Change to the monitor page [page 114], 

Locate back to the last location line [page 112]. 

Resume a process stopped at a breakpoint [page 111]. 



TOP 



TOP OF FILE 



Undo a | backtrace] [P a 9 e 112], 

Search for a specified string [page 113]. 

Set or clear a breakpoint on the current line [page 111]. 

Enables/disables hex-oriented display of constants and 
variables for C and FORTRAN [page 114]. 

Locate back to the error or last source code location 
[page 112]. 

Go to the first line in the file [page 113]. 



4.10.1 Symbolic functions 



I INSPECT 



This function displays the value and type of source code symbols. To 
inspect a symbol, use the cursor keys to position the cursor on the required 
symbol and press | INSPECT | . If the cursor is not on a valid symbol when 
| INSPECT | is pressed, a symbol name is prompted for Type | return | to 
abort the QnspecT] operation, or type a name followed by | return] . The 
case of letters in a variable name is significant — except when debugging 
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FORTRAN where case is not significant. Variable names which contain 
spaces must b e entered w ithout the spaces. Specifying an empty expres- 
sion aborts the [Inspect | operation. 

The symbol must be in scope from the line to which the debugger last 
located, which may not be different from the current cursor position. If the 
symbol is not in scope at that location, or not found at all, one of the 
following messages is displayed (depending on the language being 
debugged): 

Name * symbol' not in dynamic scope 
Name * symbol' not found 

error; identifier "name" is not in scope 
error: identifier "name" not found 

Expression language 



| INSPECT | supports an expression language for examining source file 
symbols. Details of the language and display formats for symbols can be 
found in the appropriate, language specific, sections below. 



CHANNEL | 



This function 'jumps' down a cha nnel if a proc ess is waiting at the other end. 
This is used in the same way as [ inspect | , but positioned on a channel. 
The debugger locates to the source line corresponding to the waiting 
process; that process can then be debugged. 

The | channel] function will jump to other processors along transputer 
links as long as the program has not been configured to use virtual links 
(see section 9.4 of the debugging chapter in the User Guide). If a process 
running on another processor is waiting for communication on a channel 
the debugger jumps down the link and automatically changes to that 
processor. 



INFO 



This function displays the Iptr and Wdescofthe last location, the process 
name and priority, and the processor number. 

\f the Wdesc is not in the defined region for a process the message: Unde- 
fined process is displayed in place of the process name. For single 
processor programs that have not been configured there is no defined 
region and the message: <stack area unknown> is displayed to reflect 
this. 

If a wdesc has not been supplied, it is shown as 'invalid'. 
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4.10.2 Interactive mode functions 

The following functions are only available when running in interactive mode. 



I TOGGLE BREAK 



This function toggles a breakpoi nt on the source line indicated by the cursor 
and provides information on the breakpoint number {as used by the Monitor 
page [B] command), whether it was set or cleared, and the line number 
it is on. 

When the source line the cursor is on produces no associated object code 
the debugger displays an exclamation mark (< ! >) after the line number to 
indicate that the breakpoint has been toggled on a different line to the one 
the cursor is on (as shown at the bottom of the display). 



RESUME 



This function restarts a process stopped at a breakpoint (To restart a 
process which has been stopped by one of the debug support functions use 

| CONTINUE FROM | ). 



| CONTINUE FROM | 

This function restarts the program from the line Indicated by the cursor. 
| continue FROM | should only be used to resume a process after it has 
been stopped by one of the debug support functions. The result of contin- 
uing from other points in the code may be unpredictable if there are inter- 
vening stack adjustments. 



| MODIFY | 



This function changes the value of a variable in transputer memory. For C 
and FORTRAN, | MODIFY | accepts expressions involving any symbol in 
scope. To modify a variable place the cursor on the name and press 



MODIFY 



Expression language 

Variables to be modified can be specified using the | inspect] expression 
language. Details of the syntax can be found in the following language 
specific sections. 



| INTERRUPT | 

This function forces the debugger to enter the Monitor page without stop- 
ping the program. 
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Note: This command does not operate if there are keystrokes waiting 
before it in the keyboard buffers. It may also fail if the application program 
is waiting for input from the keyboard. 

Note: A side effect of this command is that the debugger suspends 
iserver communications in order to preserve debugger output to the 
screen. 



4.1 0.3 Locating functions 

The following functions are used to change the debugger's current 'location'. The 
current location is the point at which the all symbolic functions apply — associated 
with the location are an instruction pointer value and a workspace address. The 
initial location will generally be a breakpoint (in interactive mode) orthe point where 
an error occurred (in post-mortem mode). 



BACKTRACE 



This function locates to the line where a procedure or function was called. 
If the debugger is already located in the program's topmost procedure, no 
backtrace is possible. 



RETRACE 



This function locates back t o the previo us place where the debugger was 
located. Repe ated use of | RETRACE | reverses the effect of previous 

| BACKTRACE] operations. 



RELOCATE 



This function returns the cursor to the last place located to by the debugger. 
For example, it can be used to return to the original source line of an error 
after browsing otherareas of the code with the cursor keys or the file selec- 
tion functions. 



TOP 



This function locates back to the line containing the original breakpoint or 
error, or to the line located to by the previous use of the monitor page [g] 
Offo] commands. 

4.10.4 Cursor and display control functions 

These functions are used to move the cursor around the program and to view other 
source files. 
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| GOTOLINE~l 

This function lo cates to a particular fine in the source file. Specify a line 
number, or type | RETURN | to abort the operation. 

| TOPOFFtLE~| 

Moves to the start of the current file. 



END OF FILEl 

Moves to the end of the current file. 



SEARCH | 



This function searches forwards in the source file for a specified string. 
Either specify a search string or press | return | to accept the default, 
which is the last string specified. 



ENTER FILE 



Enters an included source file. Position the cursor on the include directive 
and press I enter file] . 



EXIT FILE 



Exits from an entered include file. 



CHANGE FILE 



This function opens a different source file for reading only. No symbolic 
functions are available, unlike the Monitor page V option. 

4.10.5 Miscellaneous functions 



HELP 



This function displays a help screen of the commonly used debugger 
symbolic functions. 



GETADDRESS"! 



This function displays the address of the transputer code corresponding to 
the source line where the cursor is currently placed (not necessarily the 
current 'location*) 
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TOGGLE HEX 



This function turns the display of hexadecimal values of variables on and 
off. When enabled, the debugger displays hexadecimal as well as decimal 
values. The default for C and FORTRAN is to display variables in decimal 
format only. 



MONITOR 



This function switches to the Monitor page environment. 



FINISH 



This function quits the debugger. The Monitor page 'Q* command has the 
same effect If the command line option 'XQ' was used then the debugger 
will ask form confirmation before quitting. 
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4.11 INSPECT/MODIFY expression language for C 

The expression language for source code symbols (variables, constants, and 
channels) follows the syntax of the C programming language with some minor 
modifications. 



4.11.1 Syntax not supported 

Table 4.6 lists the standard C expression syntax not supported in the debugger 
expression language. 



Area of limitation 


Example 


Casting to pointer types 


{char *} ptr 




Calling of functions 


sqrt (x) 




Entry of strings 


"a string" 




Entry of initializer lists 


{ 1, 2, 3 J 




increment and decrement operators 


++count 




Trigraph sequences 


' ?? (' 




Bit field modification 






Modification by assignment operators 


x = y 

n += 1 




Conditional operator 


a ? b : c 





Table 4.7 Limitations to syntax 

In addition, the 'address of operator '£" returns an int rather than a pointer to the 
type. 

4.11 .2 Extensions to C syntax 

Subarrays 

The language supports the specification of array subranges for arithmetic data 
types. Subranges are specified as two array bounds separated by a semicolon. For 
example: foo[2;4] displays the values of elements foo[2], foo[3] and 
foo[4]. 

Note: For arrays and structures the information displayed will normally overwrite 
part of the screen display. Press any key, when prompted, to restore the display. 

Scope resolution operator 

The scope resolution operator ' : : ' is available when debugging both C and C++ 
programs. This allows access to a global identifier which has been hidden by a 
local declaration, for example: 
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static int £00 =42; 
void example (void) { 
int foo = 321; 

debug_stop() ; /* program will stop here */ 

} 

in this example, when the program has stopped at the debug_stop () function, 
the identifier foo can be inspected and the value 321 (the value that is currently 
in scope) will be displayed. If : :foo is inspected then the value 42 will be 
displayed. 

Hex constants 

The hex constant syntax has been extended to accept a '%' character after the 
leading ox component of a hex constant. This provides a shorthand mechanism 
for specifying transputer addresses in a similar manner to that provided in the 
Monitor page. The '%' character adds int_min (the most negative integer) to the 
hex constant using modulo arithmetic. 

For example, 0x%70 produces the value 0x80000070 on a 32 bit transputer and 
0x8070 on a 16 bit transputer. 

Address constant indirect 

When using | inspect | or | modify | a constant expression which has type int or 
unsigned int may be de-referenced. Normally only pointers may be de-refer- 
enced: this addition removes the need to change to the Monitor page to inspect 
memory locations. 

For example, *0x80000000 (or *0x%0) would display the integerat memory loca- 
tion 0x80000000 on a 32 bit processor. 



4.11 .3 Automatic expression pickup 



When | INSPECT j or | MODIFY | is selected, idebug will automatically 'capture' the 
identifier which is underneath the cursor (if any). The captured expression can then 
be modified (using the editing keys described below) before applying the selected 
option. 

In this release the automatic capture is more eager for simple struct or union 
member expressions which contain only the . and -> operators. 

This is best illustrated by example. In the following examples, the cursor is posi- 
tioned over baz when | inspect | or | modify | is selected: 



72TDS367 01 March 1993 



4 idebug ■ network debugger 



117 



Program text 


Expression captured 


baz 


baz 


baz.ptr 


baz . ptr 


*(baz) .ptr 


baz 


*baz.ptr 


baz. ptr 


baz ,ptr->ptr 


baz . ptr->ptr 


baz,foo.ptr 


baz.foo.ptr 


baz->foo->ptr 


baz->foo->ptr 


baz[x] .ptr 


baz 



In addition, for those captured expression which match the the progr am text, the 
cursor may be positioned anywhere on the expression before selecting | inspect | 
or | MODIFY | . 



4.11.4 Editing functions 

The following functions are available for the on-screen editing of expressions: 

| start of line | Move the cursor to the beginning of the expression. 

I end of lin1~| Move the cursor to the end of the expression. 

| delete UNE~| Delete the expression, 

[M\ Move the cursor left one character. 

[►"] Move the cursor right one character. 

[XI Replace the current expression with the expression used in 



DELETE ; 



RETURN 



Note: 



the previous | inspect \ or | modify | operation. 
Delete the character to the left of the cursor. 
Enter the expression for evaluation. 



| start OF lInTI , I endoflineTL I delete line] , and | delete | are mapped by 
the ITERM file to specific keys on the keyboard. Keyboard layouts can be found 
In the Delivery Manual. 



4,11,5 Warnings 

When evaluating an expression, checking is performed which may lead to warning 
messages being produced (e.g. overflow in arithmetic operation, mis-aligned 
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pointer). Such warnings are intended to highlight potential problems and to ensure 
that a user understands any action idebug is taking. 

4.11.6 Types 

G types are Interpreted and displayed by the debugger as follows: 

ANSI C types are categorized, by the debugger, as shown in table 4.8. These cate- 
gories define the operations that can be performed on the various types and are 
also used in error messages when invalid operands are used in expression syntax. 
For example, arithmetic can be performed on any of the 'scalar' types, but 
attempting to use a 'derived' type, such as a struct, in an expression produces 
an error message of the form "error*, non-scalar left-hand operand...* 



Name 


Member types 


character 


char, signed char, unsigned char 


floating 


float, double, long double 


basic 


character, signed integer, unsigned integer, floating 


integral 


character, signed integer, unsigned integer, enum 


arithmetic 


integral, floating 


scalar 


arithmetic, pointer 


derived 


array, function pointer, struct, union 



Table 4.8 Type categories in C 



Type compatibility when using | modify [ 

Source and destination expressions must be type compatible according to the 
rules of C. Scalar types are cast automatically into other scalar types but non- 
scalar expressions must be strictly compatible. 

Type conversions, where required, are performed according to normal C promo- 
lion rules. 

The following examples illustrate the rules governing type compatibility. 

Given the following declarations: 

int two_d_array[2] [10] ; 
in t one_d_ar ray [10]; 
int f oo ; 
char bar; 

Then the following modifications are permitted: 

Source: one_d_array (array of 10 integers) 

Destination: two_d_array[l] (row of 10 integers) 
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Source: f oo (a scalar type: int) 

Destination: bar (a scalar type: char) 

Source: two_d_arrayri] [2] (single element of type int) 

Destination: bar (single integer) 

The following modification is not permitted: 

Source: two_d_array [ 1 ] (row of 1 integers) 

Destinatbn: f oo (single integer) 

4.12 Display formats for source code symbols 

When displaying an object, idebug will, where possible, also display type informa- 
tion for an object (e.g. unsigned char). 



4.12.1 Notation 

The debugger uses the following symbols in its display of values: 

{ } indicates a list of values , or a structure 

{ } # * . indicates a character list of unknown 
length terminated by a null character 
(which is shown) 

' c r indicates a character 

' \HH T indicates a hexadecimal character 

" " indicates a character string in an array of 
known size 

" "... indicates a character string of unknown 
length terminated by a null character 
(which is not shown) 

< > indicates the contents of a basic or 

channel object which is addressed by a 
pointer (except when the object is 
volatile) 

( ) provides extra information about an object 

In addition, in the descriptions below, the following notation is used: 

ddd indicates a (possibly signed) decimal value 

OxHHH indicates a hexadecimal value 

fff indicates a floating point number of the 

form: ddd. ddd or ddd.dddEddd 
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4.12 Display formats for source code symbols 



4.12.2 Basic Types 

Display formats for basic C types are given in table 4.9. Displays are given in 
normal decimal format and in hex format (invoked by |TOGGLEHEx| ). 



Type 


Hex print off 


Hex print on 


char 


ddd ('c') type 


ddd {'\xHH r ) type 


short 

int 

long 


ddd type 


QxHHH (ddd) type 


float 


fff float 


fff {OxHHH) float 


double 
long double 


fff double 


fff (QxHHH) double 


For char, type is either signed char, or unsigned char. 

For integral types, type is either just the type name, or unsigned followed by the 

type name. 



Table 4.9 Basic C types 



4.12.3 Default type of "plain" char 

By default, the type of a char (known as a 'plain" char) typed into idebug is 
unsigned char. This matches the default implemented by the INMOS C 
compiler ice. If however, the default type of plain chars has been overridden with 
the C compiler ( fc' option, it may be necessary to override the default type in 
idebug by use of a cast. For example: 

(signed char) ' c' 

Note that such a cast is only necessary for a plain char entered by hand: idebug 
will correctly interpret the type of a plain char identifier contained in program code. 



4.12.4 Enumerated types 

Variables of an enumerated type are displayed as their integervalue (in exactly the 
same manner as an int) followed by the name of the enumeration and the 
enumeration constant name for the value. If there are multiple enumerated 
constants that share the same value, a list is formed containing all of the enumera- 
tion constant names, invalid enura constant is used to indicate when a value 
is not a member of an enumerated type. 

integer (enum-tag-name: enum-const-name) 

Integer { enum-tag-name : { enum-const-name , ..,}) 

integer {enum-tag-name: invalid enum constant) 
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4.12.5 Pointers 

Pointers are displayed in one of the following ways: 
OxHHH (null pointer) 
OxHHH (pointer to const volatile) 
OxHHH (pointer to volatile) 
OxHHH (channel pointer to link) 

OxHHH (channel pointer to idebug virtual link link) 
OxHHH (channel pointer to software virtual link link) 
OxHHH (channel pointer to Event in) 
OxHHH (channel pointer) 
OxHHH * (mis-aligned pointer} 
OxHHH < content of basic object > 
OxHHH (pointer) 

4.12.6 Function Pointers 

If the function pointed to is defined in the current module, then the name of the func- 
tion is displayed. 

OxHHH (function pointer to * fundionname ()") 

OxHHH (cannot find corresponding function) 

4.12.7 Structs 

Members of structures are described as for other identifiers of the appropriate type. 
In order to display structures in a readable manner, members which are derived 
types are not always displayed in as much detail as when the member occurs on 
its own. To obtain more detail, inspect the member of the structure explicitly. 

identifier = { 

memberl 
member2 
member3 

) 

For large structures, idebug pages the display and requests confirmation to 
continue after each page. 
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4.12.8 Unions 

Unions are displayed in the same manner as structs except that a question mark 
? appears to the left of each mem ber to indicate that only one member of the union 
should be selected. 

identifier = { 

? memberl 

? member2 

? members 

? : 

} 



4.12.9 Addressof operator & 

The result of the addressof operator, t, i s automatically p rinted as both a hex and 
integer value regardless of the setting of ITOGGLE HE)q . Note that the result type 
of addressof is an int rather than a pointer to the type used and is displayed in 
a similar way: 

identifier = QxHHH {ddd) 



4.12.10 Arrays 

When displaying arrays, idebug prints the valid range of each dimension {if 
known) in addition to any type information and the contents of the array. For single 
dimension arrays containing arithmetic types each member of the array is 
displayed regardless of the size of the array. For large arrays idebug pages the 
display and requests confirmation to continue after each page. For large arrays, 
where the full display may be unwieldy, use array subranging to display the area 
of interest. 

Single dimensional arrays of arithmetic types are displayed as: 

identifier = array [0..M] of type {list of values} 
Single dimensional arrays of other types are displayed as: 

identifier = array [0..M] of type 
Multi-dimensional arrays of all types are displayed as: 

identifier = array [0. .Ml [0. .N] of type 
Sub ranges of arrays are shown as follows: 

identifier [ddd;ddd} = subarray of type {list of values} 
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4.12.11 Channels 

Channels are displayed with information about the process that is waiting on the 
channel (or Empty if no is process waiting), in one of the following forms: 

identifier = Channel <Iptr: address, Wdesc: address (Lo}> 

identifier = Channel <Iptr: address, Wdesc: address (Hi)> 

identifier = Channel <Empty> 

identifier = Channel <Empty (Link link) > 

identifier = Channel <Erapty (Software virtual link Hnk)> 

An asterisk * is used to denote an incorrect Iptr or Wdesc which is not in the 
defined memory map range of the program but is in the defined memory range of 
the processor. 

A double asterisk ** is used to denote an incorrect Iptr or Wdesc which is not 
in the defined memory map range of the program and not in the defined memory 
range of the processor. 

channel (name) = Channel <Iptr: addr* , Wdesc: addr**> 

4.13 Example displays 

Tables 4.10 and 4.11 show the display formats for a number of types, using the 
following source code segment compiled for a 32 bit transputer (for a 1 6 bit trans- 
puter, addresses and integers in hex format would be displayed with 4 hex digits 
instead of 8). The program containing this code is provided as display . c in the 
C toolset debugger examples directory. 

enum colour ( red = 1 }; 
struct Many { 

int a; 

double b; 

>; 

enum colour shoe = red; 

struct Many many = { -42 , 2.0 } ; 

int answer = 42; 

char key = 'A' ; 

char string [] = "bye"; 

char* ptr = string; 

short iarray [ ] * { 1 f 2 r 3,4}; 
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4.13 Example displays 



Expression 


Display (hex print off) 


answer 


answer = 42 int 


& answer 


fianswer = Ox801FFF2C (-2145386708) int 


key 


key €5 ('A') unsigned char 


string 


string = array [0..3] of unsigned char "bye\0" 


ptr 


ptr = 0x801FFF18 < "bye"... unsigned char > 


array [ 1 ; 2 ] 


array [1;2] = subarray of short {2, 3} 


shoe 


shoe = 1 int (colour: red) 


red 


red = 1 int (enum constant) 


many 


many = { 

a = -42 int 
b = 2,0 double 

} 



Table 4. 1 Display formats with hex printing off 



Expression 


Display (hex print on) 


answer 


answer = 0x0000002A (42) int 


^answer 


fcanswer = 0x801FFF2C (-2145386708) int 


key 


key 65 f\x41') unsigned char 


string 


string = array [0..3] of unsigned char {\x62, 
\x79, \x65, \x00} 


ptr 


ptr = 0x801FFF18 < {\x62, \x79, \x65, \xO0J... 
unsigned char > 


array [1;2 
] 


array [1;2] = subarray of short {0x0002, 0x0003 
} 


shoe 


shoe = 0x00000001 (1) int (colour: red) 


red 


red = 0x00000001 (1) int (enum constant) 


many 


many = { 

a = 0xFFFFFFD6 (-42) int 

b m 2.0 (0x4000000000000000) double 

} 



Table 4.11 Display formats with hex printing on 
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4.14 INSPECT/MODIFY expression language for Occam 

The expression language for debugging Occam programs is simpler than that 
provided for C and FORTRAN — only a single identifier name can be entered for 
Inspection and only literal constants can be used as modification values. 

4.14.1 Inspecting memory 

To inspect the contents of any location in memory, specify an address rather than 
a symbol name. Type the address as a decimal number, a hexadecimal number 
(preceded by W) t or the special short form %h. . .ft, which assumes the prefix 
#8000... 

The debugger displays the contents of the word of memory at that address, in both 
decimal and hexadecimal. For more versatile displays of memory contents, use 
the Monitor page commands. 

4.14.2 Inspecting arrays 

If the symbol inspected is an array, elements from the array can be selected using 
constant integer subscripts enclosed in square brackets (' [' and ']'); if no 
subscripts are specified the debugger prompts for them. 

For short byte arrays the debugger displays the contents of the array as a string. 
Otherwise the debugger displays the size and type of the array, and prompts for 
subscript values. For example: 

[5] [4] INT ARRAY **' , Subscripts ? 

Press | RETUR N] to obtain the address of the array, or enterthe required subscripts, 
which must be in the correct range. The subscripts should be typed either as 
decimal constant integer values, or as integers separated by commas, for example 
'[3] [2]', or '3, 2\ Spaces are ignored. 

To simplify access to values indexed by variables (such as ( a [i] ') an array may 
be indexed with ' ! ■ (e.g. ( a [ t ] ') — the * ! ' character is replaced by the value of the 
last integer displayed. 

Scrolling arrays 

As well as simply displaying a single element of an array, the debugger allows an 
array to be scrolled through one element at a time. In addition, byte arrays can be 
displayed as a 16 byte 'segment' of the array —this segment can be moved up and 
down like a window into the array contents. 

Array scrolling is enabled by adding '++' after the array name when prompted for 
a symbol name, or after the subscript when responding to the 'Subscripts ?' 
prompt (entering '++' alone in response to the subscript prompt assumes a 
subscript of zero). The debugger then displays the first array element and then the 
following prompt on the second line of the screen: 

Press [UP] or IDOWN] to scroll, any other key to exit : 
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The [a] and [▼] cursor keys can then be used to scroll through the elements of 
the array. The debugger will not allow you to scroll past the beginning or end of the 
array. Pressing any other key will return you to normal symbolic mode. 

Byte arrays can be viewed in sixteen character segments by appending a '+' after 
the array name or subscript. As before, the cursor keys can be used to move the 
'window 1 up and down the byte array one character at a time. Using '+' on anything 
other than a byte array behaves identically to using f ++'. 

4.14.3 Type compatibility when using | modify | 

Once a variable is selected the debugger prompts for a new value. The new value 
should be specified in the expected Occam type (as specified within the prompt) 
although there are a few relaxations to this rule to allow for implicit casts when 
using the debugger (see below). REAL32 and REAL64 values must be given in the 
correct Occam format — including a sign for the exponent, if present 

The following Occam types may be freely mixed to provide implicit type casts so 
long as the value is defined within the destination type: 

BOOL BYTE INT INT16 INT32 INT64 

The following are examples of valid modification values: 



Type 


Modify value 


REAL32 


42.0 




INT64 


TRUE 




INT 


'a' 




BOOL 


1 




BOOL 


'*#00' 




INT16 


#A0 




INT32 


$1A 




BYTE 


42 





The following are examples of invalid modification values: 



Type 


Modify value 


REAL32 


42 


INT 64 


2.0 


BOOL 


'*#02' 


INT16 


32768 


BYTE 


-1 


BYTE 


#100 
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4.15 Display formats for source code symbols 

When displaying an object, idebug will display its type and value, together with 
its address in memory. If there is too much information to be displayed on one line, 
it is displayed in two parts. The symbol's name and type is displayed first and then, 
after a short pause, the value and address. 

The display formats for the basic Occam types (BOOL, BYTE, INT, INT16, INT32, 
INT64, REAL32 and REAL64), channels, arrays, and procedures and functions 
are described below. For protocol names and tags, and timers only the type and 
name are displayed. 



4.15.1 Notation 

The debugger uses the following symbols in its display of values: 

' c' indicates a character 

" " indicates a character string 

( ) provides extra information about an object 

(at shows the memory address of an object 

ihhh) 

In addition, in the descriptions below, the following notation is used: 

ddd indicates a (possibly signed) decimal value 

thhh indicates a hexadecimal value 

fff indicates a floating point number of the 

form: ddd. ddd or ddd.dddEddd 

bbb indicates a boolean value (TRUE or FALSE) 

4.15.2 Basic Types 

Display formats for the basic occarn types are given in table 4.12. When debug- 
ging Occam programs, the debugger always displays both decimal and hexade- 
cimal values for integertypes (regardless of the state invoked by |TOGGLE HEXj ). 
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Type 


Display 


BYTE 


BYTE 'name' has value ddd {thh t r c r ) (at thhh) 
Note: non-printing characters are displayed as r . ' 


BOOL 


BOOL % nam&* has value bbb {at thhh) 


INT 
INT16 
INT32 
INT64 


type 'name' has value ddd (thhh) (at thhh) 


REAL32 
REAL64 


type "name' has value fff {thhh) (at thhh) 



Table 4.12 Display formats for basic occam types 

If a variable is optimized out because it is not used in the program, then the 
following message is displayed: 

type *name r was never used and has been optimised out. 

4.15.3 Channels 

For channels, which are not empty, the iptr and wdesc of the process waiting for 
communication, and its priority, are displayed. 

Channels are displayed in one of the following forms: 

CHAN "chan' is empty (at thhh) 

CHAN "Chan 1 has Iptr: thhh and Wdesc: thhh (Lo) (at thhh) 

CHAN "Chan 1 has Iptr: thhh and Wdesc: thhh (Hi) (at thhh) 

An asterisk * is used to denote an incorrect Iptr or Wdesc which is not in the 
defined memory map range of the program but is in the defined memory range of 
the processor. 

A double asterisk ** is used to denote an incorrect iptr orwdesc which is not in 
the defined memory map range of the program and not in the defined memory 
range of the processor. 

CHAN *chan> has Iptr: thhh* and Wdesc: thhh (Hi) (at 
thhh**) 

If the channel is a hard channel then information about the link (or event channel) 
that it is mapped onto is also provided. For example: 

CHAN y ts r is empty (Link 1 in) 

If the channel is a software virtual link provided by the configurer, then the virtual 
link number is displayed. However, this does not show whether this is an input or 
output virtual link. For example: 

CHAN *fs' is empty (virtual Link 41 at thhh) 
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4.15.4 Arrays 

If subscripts are specified then the type, value, and address of the array element 
are displayed as described above. 

If no subscripts are given then, for a short byte array the contents are displayed 
in ASCI!. For any other type of array, just the dimensions, type and address of the 
array are displayed. 



4.15.5 Procedures and functions 

For procedure or function names, the entry address, and nested workspace and 
vectorspace requirements are displayed {no address is displayed for library 
names): 

proc "name' at %hhh r uses ddd ws and ddd vs slots 

FUNCTION x name T at ihhh, uses ddd ws and ddd VS slots 

4.16 Example displays 

Table 4.13 shows trie display formats for a number of types, using the following 
source code segment compiled for a 32 bit transputer (for a 16 bit transputer, 
addresses and integers in hex format would be displayed with 4 hex digits instead 
of 8). 
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— Debugger example: display, occ 

— Example of occam display types within i debug. 

— Note: This example uses the PAR construct in an 

inefficient manner for illustrative purposes only. 



#INCLUDE "hostio.inc" 
# INCLUDE "linkaddr.inc" 
#USE "hostio.lib" 
#USE "debug. lib" 

PROC example (CHAN OF SP fs, ts, []INT free. memory) 
VAL name IS "occam example" : 

CHAM OF INT ca, cb : 
PLACE ca AT event. in : 
BOOL bool : 
BYTE byte : 
INT int : 
INT16 intl6 : 
INT32 int32 : 
INT 64 int64 : 
REAL32 real32 : 
REAL64 rea!64 : 
[20] [32] INT grid : 
[256] BYTE string : 
INT at, y : 
INT not. used : 
SEQ 
PAR 

ca ? x 

cb ? y 

bool := TRUE 

byte := 'B' 

int := -42 

intl6 := -42 (DTT16) 

int32 := -42 (INT32) 

int64 := -42 (INT64) 

real32 := 1.0 (REAL32) 

real64 : = 1.0 {REAL64) 

grid[0] := grid[l] 

[string FROM FOR SIZE name] := name 

IF 

(SIZE free. memory) > 
free. memory [0] :— €6 
TRUE 
SKIP 



72TDS 367 01 March 1993 



4 idebug - network debugger 



131 



DEBUG. STOP (} — debugger will locate to here 

so.exit(fs, ts, spa. success) 



SymboJ 


Display 


ca 


CHAN *ca' . . . 

(then, after a pause) 

has Iptr: #80G03EAE and Wdesc; #80003DE5 (Lo) 
(PLACED AT 8) (Event in) 


cb 


CHAN ^cb' has Iptr: #80003EB5 and Wdesc: 
#800G3DD9 (Lo) (at #80003E24) 


not. used 


INT * not. used' was never used and has been 
optimised out 


bool 


BOOL *bool r has value TRUE (at #80003E20) 


byte 


BYTE 'byte' has value 66 {#42, 'B') {at 
#80003E1C) 


int 


INT 'int' has value -42 (#FFFFFFD6) {at 
#80003E18) 


int 16 


INT 16 'intlS' has value -42 <#FFD6) {at 
#80003E14) 


int32 


INT32 Unt32' has value -42 (#FFFFFFD6) (at 
#80003E10) 


int64 


INT64 *int64' has value -42 
{#FFFFFFFFFFFFFFD6) {at #80003E08) 


real 32 


REAL32 'real32' has value 1.0 (#3F800000) (at 
I80003E04) 


real 64 


REAL64 1 real64 / has value 1.0 
(#3FFOOOOOOOO0OOOO) (at #80003DFC) 


grid 


[20] [32] INT ABRAY 'grid' {at #800041D8) 
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4.16 Example displays 



Symbol 


Display 


string 


[256]BYTE ARRAY 'string' {at #80004BD8) 


string + 


[16]BYTEs from 'atringlOJ' is "occara 
example..." (at #80004ED8) Press [UP] or 
[DOWN] to scroll , any other key to exit : 


string ++ 


BYTE l »tring[0] r has value 111 (#6F, 'o') (at 
I80004BD8) Press [UP] or [DOWN] to scroll, any 
other key to exit : 


example 


PROC 'example' at #80QQ3E4C, uses 74 WS and 
706 VS slots 


DEBUG, STO 
P 


LIB PROC ^DEBOG.STOP' uses 25 WS and VS 

slots 



Table 4.13 Occam display formats 
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4.17 Error messages 

This section lists error messages generated by idebug. Other messages not in 
this list may be generated by corrupt files and by files not created by the toolset. 



4.17.1 Out of memory errors 

If the debugger runs out of memory when trying to read in information and the 
offending code module cannot be reduced in size, the amount of memory available 
to the debugger may be increased by increasing the size of the memory on the 
transputer the debugger is running on and updating IDEBUGSIZE accordingly. 



4.17.2 If the debugger hangs 

If the debugger starts up but then hangs with the message: 

Loading network . . . 
one of the following errors may have occurred: 

1 The network connectivity is not correctly described in the configuration 
description, for example, a link is not connected to a processor, or the type 
of a processor has been specified incorrectly. 

Network connectivity on a board can be checked by running a check or 
worm program, such as the ispy program supplied with the support soft- 
ware for some INMOS /q systems products. These products are available 
separately from your local INMOS distributor. 

2 You have set idebugsize to be larger than the memory on the root 
processor (where the debugger is running). 

Change idebugsize to reflect the correct root processor memory size. 

4.17.3 Error message list 

"Filename" not compiled with full symbolic debug information 

The object code module does not contain sufficient debug information for 
the debugger to locate to its corresponding source code (i.e. it contains 
minimal debug information). Recompile the module and rebuild the 
program in order to debug it symbolically. 

Already located - No process is waiting at the other end of this link 

An attempt to jump down a hard channel (link) has failed because there is 
no process waiting at the other end. 
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Attempted read outside Parameter block 
Attempted write outside Parameter block 

The configuration system has become corrupted. Check hardware using 
a memory check program such as ispy. (The ispy program is supplied 
as part of the board support software for INMOS /'q systems products. 
These products are available separately from your local INMOS distrib- 
utor.) 

Can only specify a transputer type if bootable is for a class 

Cannot specify a transputer type for configured bootable files 

You have tried to specify a processor type when the bootable file is already 
for a specific processor type. 

Cannot create network dump - reason 

Creation of a network dump file is not permitted on a program that is, or has 
been, interactively debugged, reason can be either of the following: 

1 when in Interactive mode 

2 when in Postmortem Interactive mode 

3 Already reading one 

Cannot debug boot from ROM run in ROM file "Filename" 

You may only debug boot from ROM run in BA M programs with idebug. 

Cannot find this line's location 

Either of the following has occurred: 

1 You have moved the cursor beyond the end of the current source 
file for which there is no executable code. 

2 The compiler has optimized the executable code out. 

Cannot locate beyond Freespace area 

The address specified is not within the memory map range of the 
processor. 

Cannot locate to area (Iptr: #address) 

The address specified is not within the code area for the program on the 
processor, area can be any of the following: 

Reserved transputer memory 

Runtime kernel 
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Reserved memory 
Configuration code area 
Stack area 
Vectorspace area 
Static area 
Heap area 
Freespace area 

Cannot open "filename" 

Either the file does not exist or it is not on the isearch path (note that by 
default this includes the current directory). The ilist tool can be used to 
confirm this. 

Note: if the file name is vrdebxx. tco (or something similar), where xx is 
a sequence of digits, then you are probably trying to locate to one of the 
configurer's software virtual link processes. Use the [T] command to 
display processes waiting on the software virtual links. 

Cannot read processor number (Txxx) 

The debugger cannot communicate with that processor Any of the 
following errors may have occurred: 

1 The root processor's core dump has been incorrectly specified. 

2 The debugger has failed to analyze the network correctly. Either 
you have failed to specify the 'A 1 option or the system control 
signals are wired incorrectly. 

3 The network does not match that specified in the configuration file. 
Check network connectivity using a check program such as ispy. 
(The ispy program is supplied as part of the board support soft- 
ware for INMOS ;'q systems products. These products are avail- 
able separately from your local INMOS distributor.) 

Cannot run application - the program has crashed I 

Use the [T] (Enter post-mortem debugging) Monitor page command to 
post-mortem debug the (now defunct) breakpoint session. 

Channel is invalid 

The channel does not point to a known process executing on the processor. 
Configuration info inconsistent with linked unit 

You have probably relinked a component of a program and forgotten to 
reconfigure it. 
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Configured for post-mortem debugging only 

You have explicitly disabled interactive debugging (using configurer or 
collector options). 

Debug info too large ( reason ) 

The debugging information for a particular compilation module is too large 
forthedebugger. Either reduce the size of the offending module or increase 
the size of memory on the processor where the debugger is running (see 
section 4.17.1 on how to overcome this). 

reason can be any of the following: 

ix.tags is full 
ws.array is full 
name table is full 

Debugger Incompatible configuration file "filename" 

You have configured your program without specifying the debugger 
compatible option ('G' option) to the configurer, icconf . 

For mixed language programs configured with the occam toolset confi- 
gurer occonf , the error may be that you have configured your program 
with the configurer "RE" option to enable memory layout re-ordering. 

File has changed since configuration "filename" 

You should rebuild the program again. 

FILE IS TOO BIG - truncated 

The debugger buffer capacity has been exceeded. The buffer contains as 
much of the file as could be read before the capacity was exceeded (see 
section 4.17.1). 

Illegal virtual channel address 

The channel has been (possibly incorrectly) tagged as virtual but does not 
point to a valid software virtual channel (as defined by the deb ugging kernel 
or the configurer). This is caused by a channel that has become corrupted 
(normally by overwriting the location of the channel). You should ensure 
that no compiler checks have been disabled to prevent accidental corrup- 
tion. 

Incompatible debugger modes: message 

Mutually incompatible options have been specified on the command line. 

Interactive debugging has been disabled 

The module has been linked with the linker T option to disable breakpoint 
(interactive) debugging. Rebuild your program without disabling interactive 
debugging and retry. 
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ITERM error on line linenumber, message 

The debugger has detected a syntax error in the ITERM file, message 
describes the error. 

Name symbol is not in dynamic scope 

The symbol symbol exists in the module, but is not in scope from where the 
debugger last located to. In order to inspect the symbol you must locate to 
a new position where the symbol is in scope. 

Not a (compatible) bootable file "filename 1 * 

The file is either a non-bootable file or a pre-product release bootable file. 
Use ilist to determine the contents of the file if in doubt. 

Not enough free memory for the debugger 

You have either not set the environment variable idebugsize or you have 
set it to be too small (it should be > 400K). Change the variable to reflect 
the memory size of the root processor. 

Not on a valid INCLUDE line 

You may only use ] enter file"! when the cursor is on a line with an include 
directive. 

Only debugging tools and cursor keys are available 

You have pressed a key which is not defined. 

Option must be followed by a link number (0 - 3) 

Command line options 'B\ i M', and 'T' require a link number in the range 
to 3. 

Option must be followed by a valid processor type (eg. T425) 

The processor type supplied is not recognized by the debugger. 
(Probe Go) : Processor number- Cannot contact 

The debugger is unable to communicate with processor number. The 
processor type specified in the configuration (or to the debugger via the 'C 1 
option) does not match that found. Check the network using a program 
such as iapy in order to determine the correct processor type, 

(Probe Go) : Processor number- Expected processor type Txxx, found Ixxx 

The processor type specified in the configuration (or to the debugger via 
the 'c' option) does not match that found. Check the configuration descrip- 
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tion and the network (using a program such as ispy) in order to determine 
the correct processor type. 

(Probe Resume) : Processor number- Invalid Breakpoint 

The debugger has stopped at a breakpoint which it did not place in the 
code. If you wish to continue executing the program set a breakpoint at the 
same address and retry the command. 

Processor number : insufficient memory, require at least number bytes 

The memory requirement of the processor as specified to the configurer, 
the collector, or in iBOABDSiZE(as appropriate) is too small, (Note that the 
value displayed may include memory for some configuration code that is 
reclaimed when program starts executing.) 

This may also be caused by the debugging Runtime kernel using an extra 
11— 15K of memory. 

Processor type must be a 32 bit processor (eg. T425) 

You must specify a 32 bit processor type because processor classes are 
for 32 bit processors only. 

Processor type must be not abbreviated 

You must specify specific processor types rather than abbreviated types 
(e.g. T425 rather than T5) because some abbreviated types cover more 
than one specific type. 

READ ERROR - truncated 

The debugger could not read all of the file. The buffer contains as much of 
the file as could be read (see section 4.17.1 on how to overcome this). 

Runtime kernel is not present (or has been overwritten) 

Either the runtime kernel has been corrupted or you are trying to post- 
mortem a breakpoint session that didn't occur 

There is no enclosing INCLUDE 

You have attempted to use | EXIT FILE | when not located in a nested 
include file. 

There are no processes waiting at either end of this link 

An attempt to jump down a hard channel (link) has failed because there are 
no processes waiting at either end. 

This transputer link is connected to the host 

The link specified in the 'B', ll', or 'T' command line option is the commu- 
nication link from the debugger to the host and is not connected to the 
network. 
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Too many processes declared at configuration level { number ) 
Too many processes used at configuration level ( number) 

The debugger requires more memory in order to operate on this many 
processes (see section 4.17.1 on how to overcome this). 

Too many processors - There is only enough room for { number ) 

The debugger requires more memory in order to operate on this many 
processors (see section 4,17.1 on how to overcome this). 

Unable to find any low priority entrypoints on any processor 
Unable to find any low priority entrypoints on this processor 
Unable to find any low priority main () on this processor 

The processes you have requested the debugger to set breakpoints in are 
all at high priority on processors with no hardware breakpoint support. 

Unable to read environment variable ITERM 

There is no translation for the ITERM environment variable which defines 
the screen and keyboard format 

Unable to toggle a breakpoint on this line 

The breakpoint cannot be set or cleared on this source line. Either 

1 The current file contains no executable code, or 

2 Executable code is contained in an include file and the debugger 
cannot determine whether you mean to toggle the breakpoint in 
that file or in the current file. 

Move to the line where you really want to toggle the breakpoint and retry 
the command. 

Unknown core dump format "filename" 

The network dump file is in the wrong format or the wrong file has been 
specified. You can use ilist to determine the format of the file. 

Wdesc is invalid - message 

The Wdesc supplied is invalid: this may be deliberate because it is 
unknown. If you supplied it from the Monitor page environment, retry the 
command with a valid wdesc. 

message can be one of: 

cannot inspect variables 
cannot modify variables 
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cannot backtrace 

cannot auto backtrace out of library 

Wrong number of processors In network dump file filename 

The number of processors does not correspond to the current program. 
The wrong network dump file may have been specified. 

You cannot backtrace from here (to configuration code) 

This normally occurs when you try to backtrace from the program's topmost 
procedure into the bootstrap routine which is not supported symbolically by 
the debugger (i.e. the configuration code area). 

You cannot backtrace from here (to Iptr: #r?nn, Wdesc: #mmm) 

An attempt to backtrace from a procedure or function has failed because 
the resultant process details are invalid (e.g. iptr is not in the Code area), 
or you are trying to locate to a software virtual link router process.. 

The iptr and wdesc shown are those of the invalid process which 
supposedly called the current procedure or function. 

If this error occurs, you should use | INFO | before backtracing to check that 
the current process details are valid (they are normally only invalid when 
incorrect process details have been specified with the Monitor page c o* 
command). Corruption of the stack (workspace) is another possible cause 
of this error; to prevent accidental corruption you should ensure that no 
compiler checks have been disabled. 

This error can also occur if you try to locate to a process which implements 
the software virtual links. This can be checked by using the [v] command 
to search for a process with a Code area which contains the displayed 
Iptr and a stack area which contains the displayed Wdesc. If the name 
of the process is "%router [n] * then it is a software virtual link process 
which can not be located to. 

You have changed file, so you can't use this key 

There are certain symbolic features that cannot be used if you have 
changed to another source file. Either use | RELOCATE | , or relocate to the 
original file using the Monitor page |T] (Select file) command, before 
retrying the command. 

You must specify a filename 

The command line syntax requires a filename. 
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You must specify a transputer type (bootable is for a TA class) 
You must specify a transputer type (bootable is for a TB class) 

The program you are trying to debug is for a transputer class (either T A or 
TB); the debugger needs to know the actual processor type (e.g. T425). 

You should retry using the debugger with the command line 'C option to 
specify the appropriate processor type. 

You must specify the application boardsizein IBOARDSIZEto be <= #10000 
On a T2 the maximum memory size is 64K (#10000). 
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5 idump — memory 
dumper 



This chapter describes the memory dumper too! idump that dumps the contents 
of the root processor's memory to disk. It is used to enable the debugging of code 
running on the root transputer. 

5.1 Introduction 

The memory dumper allows programs that use the root transputer to be debugged 
in the normal way using the debugger tool idebug. It is required because idebug 
runs on the root transputer and overwrites all code and code in Its memory, idump 
saves the contents of the root transputer to a disk file in a format that can be read 
by the debugger Information contained in the file allows the debugger to analyze 
data in the root transputer in the same manner as othertransputers on the network. 

When idump is invoked it calls the server with the 'SA* option so that the space 
occupied by the dumper program is saved before it is loaded onto the transputer. 

5.2 Running the memory dumper 

To invoke the idump tool, use the following command line: 

► idump filename memory size [{startoffset length }] 

where: filename is the name of the dump file to be created. 

memorysize is the number of bytes, starting at the bottom of memory, to 
be written to the file. 

startoffset is an offset in bytes from the start of memory. 

length is the amount of memory in bytes, starting at startoffset, to be 
dumped in addition to memorysize. 

All parameters can be expressed in either decimal or in hexadecimal format. Hexa- 
decimal numbers must be preceded by the hash character *#' or the dolEar sign '$'. 

The memory dump file stores the contents of the transputer's registers and the first 
memorysize bytes of memory. The file is given the . dmp extension. Afterthe dump 
has been performed idump remains resident on the transputer board ready to 
load the debugger. 
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memorysize must be large enough to contain the complete program with its work- 
space and vectorspace. If the program to be dumped uses the free memory buffer, 
the whole of the transputer board's memory should be dumped. 

Further portions of memory can be dumped by specifying the start of the segment 
of memory to be dumped and the number of bytes, using pairs of startoffset length 
parameters. The start address is given by startoffset and the number of bytes by 
length. The overall size of the memory dump file is given by the amount of memory 
saved plus around 500 bytes for the register contents. 

5.2.1 Example of use 

Assuming a value of 1 0OK for iboardsize: 

idump core 102400 

This command writes the contents of the root transputer's memory to the file 
core . dmp. The . dmp extension is added by default because the filename is 
specified with no extension. 

5.3 Error messages 

Badly formed command line 

Command line error. The command syntax requires a file name followed 
by the number of bytes of memory to dump. Check the syntax of the 
command and retry. 

Cannot open file 

File system error. The memory dump file could not be opened on the host 
system. 

Cannot write file 

File system error. The memory dump file could not be written to the host 
system. 

You must tell the server to peek the transputer 

idurap has been invoked by calling the host file server with the incorrect 
option. This error can only occur if the tool is not invoked with the supplied 
driver file. 
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This chapter describes the memory configuration tool iemit. This tool can be 
used interactively to explore the effects of changes in the external memory inter- 
face parameters of certain 32 bit transputers. The tool can also be used in batch 
mode to create ASCII or PostScript files. The tool produces a memory configura- 
tion file which may be included as an input file to ieprom and blown into EPROM 
along with a ROM-bootable application file. 

The chapter describes how to use iemit and outlines its capabilities. Example 
displays are provided, followed by a List of error messages which the tool may 
generate. The format of the memory configuration file is described and an example 
is given. Note: memory configuration files are simple text files which may be 
created manually using a standard text editor or generated by using iemit. 

6.1 introduction 

The IMS T400, T414, T425, T426, T800 and T805 transputers have a configurable 
external memory interface (EMI) which allows a variety of types of memory device 
to be connected using few extra components. 

For these transputers, the interface configuration may be selected by one of two 
mechanisms. The user may select one of the 1 7 standard memory configurations 
(13 for the T414) or a customized memory configuration may be loaded from a 
ROM or PAL on reset. 

Both methods of memory configuration are available when booting from ROM or 
from link. If the transputer is being booted from ROM, a customized memory 
configuration may be added to the ROM or a standard configuration may be used. 
If the transputer is booted from link a standard configuration may be used at no 
extra cost, or a dedicated ROM or PAL may be added for a customized configura- 
tion. 

In order to generate a customized configuration the user may create a memory 
configuration file, describing the memory configuration and have this blown into 
an EPROM. The configuration chosen is made known to the transputer by simple 
board level connections which are detected by the transputer on reset. If a stan- 
dard configuration is required the MemConfig pin is connected to the appropriate 
address pin. For example, standard configuration 7 is selected via address pin 
MemAD7. If a customized configuration is required the MemConfig pin is 
connected though an invertor to the appropriate data line, usually this is 
MemnotWrDO, Note; when iemit is used to generate the memory configuration, 
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the MemnotWrDO pin must be used. For further details see The transputer data- 
book. 

The external memory interface configuration tool iemit produces timing 
diagrams for potential configurations of the memory interface and warns of 
possible errors in the design. It indicates whether one of the preset configurations 
that are available would be suitable, or whether it would be necessary to use an 
externally programmed configuration. 

Note: That it is assumed that readers creating memory configuration files are 
familiarwith the memory interface of the processor that they are using. The stages 
in designing a memory interface, including examples, are described in chapter 2 
of The transputer applications notebook - Systems and performance. Further 
information may also be found in The transputer databook. 

6.2 Running iemit 

The iemit tool can be invoked by the following command line: 

^ iemit options 

where: options is a list of options given in Table 6.1 . 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and ca n be given in any 
order. 

Options must be separated by spaces. 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Option 


Description 


A 


Produce ASCII output tile. 


£ 


Invoke interactive mode. 


F filename 


Specify input memory configuration file. 


I 


Select verbose mode. In this mode the user will receive status 
information about what the tool is doing during operation for 
example, reading or writing to a file. 


filename 


Specify output filename. 


P 


Produce PostScript output file. 



Table 6.1 iemit command line options 

Note: that if option 'e' is selected i.e. interactive mode, then no other options may 
be specified on the command line. 
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The operation of iemit in terms of standard file extensions is shown below: 




Examples of use 

iemit may be invoked in interactive mode by using one of the following 
commands: 

iemit -e (UNIX based toolsets) 

iemit /« (MS-DOS and VMS based toolsets) 

Output files in ASCII or PostScript may be specified by command options from 
within interactive mode; alternatively iemit may be invoked in batch mode, to 
create an output file in one of these formats. 

When the tool is invoked in batch mode to produce an output file in either ASCII 
or PostScript format, then an input file must be supplied using the 'f' option. It is 
also mandatory to specify either the 'A' or 'p' option. If the '0' parameter is not 
supplied then an output filename will be constructed, from the input filename, with 
an extension of \ps' for a PostScript output, or'.asc'foran ASCII output. 

Example: 

The following commands cause iemit to produce an output file in PostScript 
format. The tool is invoked in verbose mode. 

UNIX based toolsets: 

iemit -i -p -f memconf ig . mem -o waveform.ps 
MS-DOS and VMS based toolsets: 

iemit /i /p /f memconf ig , mem /o waveform.ps 

Note: iemit will make use of the ITERM host environment variable, if it is avail- 
able, otherwise it will use defaults. 
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6.3 Output files 

Two different types of output may be produced by iem.it, these are listed below: 

• A memory configuration file suitable for including as an input file to the 
iepromtool. 

• An output file in either ASCII or Postscript format, suitable for inclusion in 
documentation. 

The tool may be used interactively to produce a memory configuration file in text 
format. This file may then be used as an input file to the ieprom tool, thus enabling 
the memory configuration to be stored on ROM. iemit is capable of saving and 
reloading configurations to allow for design over an extended period and for 
comparison of different configurations. The memory configuration file is described 
and an example is given in section 6.6. 

Additionally iemit may be used to produce an output file which is either a plain 
ASCII file containing timing data or a file in PostScript format containing waveform 
diagrams. These formats were chosen so that the results of the program could be 
easily included in reports or other documentation. 

6.4 Interactive operation 

When iemit is invoked in interactive mode the program will start up with the 
default standard configuration 31. 

The tool's user interface is presented as a number of display pages showing timing 
data. The displays may be updated by changing the timing parameters, which are 
accessed from page 1. All inputs are executed immediately so that the user can 
see the effect on any of the displays. As each page is shown, the user has the 
option of selecting another page for display by keying in its number. The current 
configuration may be saved at any time to a specified output file. 

The information displayed and options available on each page are described 
below, 

6.4.1 Page 

This page acts as an index to the others. It shows the title of each page and allows 
one of them to be selected. An option is provided to enable an input file to initialize 
the memory configuration. Other options enable the user to selectively generate 
output files. Options are listed in table 6.2 and an example of the display page is 
given in figure 6.1. 



The user enters an option code followed by the | RETURN ] key. If a file option is 
specified the user will be prompted for a filename. Note: file extensions should be 
specified, there are no defaults. 
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Option 


Description 


1 to 6 


Selects the page to be displayed. 


Q 


Quit - selection of this option exits the program. 


L 


Load previously saved configuration. A filename is prompted for, 
and the configuration saved In that file is read in and the display 
data is updated. The program expects a memory configuration file. 

If loading does not succeed because the file has a bad format, the 
current configuration is reset to standard configuration 31. If 
loading fails because the file could hot be found or could not be 
opened for reading, the load is abandoned without losing the 
current configuration. 


S 


Save configuration to a file. The program prompts for the name of 
a file to which the data will be written, by convention the extension 
.mem should be used. Output is a memory configuration file. An 
error is reported if the data could not be saved. The saved file is 
given comments in its header indicating that it was created by the 
iemit program. 


A 


Output pages in ASCII format to a file. The program prompts for 
the name of a file to which the data will be written. Output is in plain 
ASCII format with a form feed (FF) character after each page. It 
includes fall timing information and a representation of the timing 
diagrams for read and write cycles. An error is reported if the 
output could not be written. 


P 


Generate PostScript file. The program prompts for a filename. The 
program writes to the file a program in the PostScript page descrip- 
tion language to draw the timing diagrams for the chosen memory 
interface configuration. The waveforms shown are the same as 
those which can be seen by selecting pages 4 and 5. 

The file produced fully conforms to the PostScript structuring 
conventions, allowing it to be processed by other programs. The 
diagram is designed to fit lengthways on an A4 page, and is suit- 
able for inclusion in technical notes and reports. The file can be 
sent directly to an Apple LaserWriter or other PostScript output 
device. 



Table 6.2 iemit page options 
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6,4 Interactive operation 



f Page 



T414/T800 External Memory Interface Program 



Please enter 1, , . 

<s> 

<L> 
<A> 

<P> 

<Q> 



Page 



Index - this page 

EMI configuration parameters 

General timing 

Dynamic RAM timing 

Read cycle waveforms 

Write cycle waveforms 

Configuration table 



to see a new pager 

to save configuration to a file; 

to load a saved configuration ,- 

to generate an ASCII listing of all pages to a file; 

to generate PostScript file of waveforms; 

to exit the program. 



Figure 6.1 Example iemit display page 



6.4.2 Page 1 



This page shows the input parameters to iemit. It is from these parameters that 
the tool computes the timing information and the waveforms. Only one parameter 
may be changed at a time and the display data is immediately updated. An 
example of the display page is given in figure 6.2. 



Page 1 



EMI configuration parameters 



Device type 






T425 


-23 






EMI clock period Tm 






20ns 


i- 


Clockln 


.._ 


Wait states 















Address setup time 






sis 


k 


periods 


Tm 


Address hold time 






T2: 


A 


periods 


Tm 


Read cycle tristate/write data setup 


T3i 


A 


periods 


lis 


Extended for wait 






T4: 


A 


periods 


m 


Read or write data 






55: 


4 


periods 


m 


End tristate/data hold 






TfiJ 


4 


periods 


Tm 


Nonprogrammable strobe 


"notMemSO ■ 


"Q* 


50 








Programmable strobe 


"notMemSl * 


.1-1! 


SI: 


30 


periods 


m 


Programmable strobe 


n notMemS2 * 


ft JJf 


S2: 


30 


periods 


r» 


Programmable strobe 


H notMemS3 ■ 


"2" 


S3: 


30 


periods 


TYn 


Programmable strobe 


"notMemS4 ■ 


"4 * 


54: 


18 


periods 


Tm 


Read cycle strobe 


"notMemRd * 


n ^" 










Write cycle strobe 


"notMemWrB* 


"*-■' 










Rsfresh. period: 72 Clock/In periods 








Wait: 





Write mode: Late 






Configuration: 


31 



5 MHz 



Enter a new page number (0 for the index) or <C> to change a parameter: 



Figure 6.2 Example iemit display page 1 

When the page is displayed, the user has the option to select a new page by 
entering its number, or entering £c] to change one of the parameters. In the latter 
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case, a list of parameter identifiers is displayed (see table 6.3) and the user is a 
prompted to select one. The user may then specify a new value, or by pressing the 
j return | key, leave the current selection unchanged. The parameters used for 
modifying the timing data are described in tables 6.4, and 6,5. 



Parameter 
identifier 


Parameter 


to 6 


Page to be displayed 


D 


Device type 


Tl 


Address setup time before address valid strobe 


T2 


Address hold time alter address valid strobe 


T3 


Read cycle instate or write data setup 


T4 


Extendible data setup time 


T5 


Read or write data 


T6 


End Instate or data hold 


SO 


Non-programmable strobe "notMemSO" 


51 


Programmable strobe "notMemSI" 


S2 


Programmable strobe "notMemS2" 


S3 


Programmable strobe "notMemS3" 


S4 


Programmable strobe "notMemS4" 


RS 


Read cycle strobe name 


ws 


Write cycle strobe name 


R 


Refresh period 


WM 


Write mode 


W 


Memwait input connection 


c 


Standard configuration 



Table 6.3 iemit page 1 parameter identifiers 

Note: there are two parameters displayed on page 1 which are calculated by 
iemit and cannot be directly updated by the user; they are the EMI clock period 
Tm and the Wait states (see Table 6.5). 
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6.4 Interactive operation 



Parameter 


Description 


Device type 


This parameter enables the program to deduce the time 
taken for a half cycle of the signal ProcCIockOut: this is 
Tm, the basic unit of time of the memory interface. A menu 
of the available devices is displayed and the user is invited 
to select one: 

T400-20 T800-17 
T414-15 T800-20 
T414-17 T800-22 
T414-20 T800-25 
T425-17 T800-30 
T425-20 T800-35 
T425-25 T805-25 
T425-30 T805-30 


Tstates T1-T6 


The length of each Tstate T1 to T6, is entered as a number 
of Tm periods between 1 and 4. (2 Tm periods = 1 clock 
cycle). 


Programmable 
Strobes S0-S4 


The programmed durations of the strobes notMemSO to 
notMemS4. The strobes each have two names which can 
be altered. One which can be up to 9 characters in length, 
and one consisting of just one character. There should be 
no embedded spaces in the long names. The short names 
are used in the timing information on pages 2 and 3, while 
the long names are used to label the waveforms on pages4 
and 5, and in the PostScript output. The signal names are 
initialized to sensible defaults. 
Note: that SO is a fixed strobe, so its duration cannot be 
changed. The duration of a strobe can be to 31 Tm 
periods. If the value for S1 is set to zero, then notMemSI 
stays high throughout the cycle; if the value for S2, S3 or 
S4 is set to zero, then the strobe is low for the duration of 
the cycle. 


Read strobe 
name 


The names for the read strobe notMemRd can be altered. 


Write strobe 
name 


The names for the write strobe notMemWrB can be 
altered. Note that because the four byte write strobes have 
the same timing, only one is considered 


Refresh 
period 


The refresh period is given as a number of Clockln periods 
(1 8, 36, 54, or 72) or as Refresh Off if zero is selected. 



Table 6.4 iemit page 1 parameters 
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Parameter 


Description 


Write mode 


The write mode can be set to Eariy or Late to suit 
the type of memory being used. 


Wait connection 


The MemWait input may be connected to one of 
the strobes S2, S3, S4 by entering 'S2\ 'S3' or'S4' 
respectively. Alternatively, by specifying a 
number in the range 1 to 60 MemWait may be 
connected to a simulated external wait state 
generator. This causes MemWait to be held high 
then to become inactive (low) a set number of Tm 
periods after the start of T2, Note: that this mode 
is not supported directly by the T414; in a final 
design, a circuit would have to be built to perform 
this function. 

If the current connection of MemWait causes the 
signal to become inactive just as ProcClockOut 
is felling during T4, a warning is given that there 
is a hazard of a wait race condition. This is 
because MemWait is sampled on the falling edge 
of ProcClockOut -and if the signal is changing 
while being sampled, the result is undefined. 


EMI clock period Tm 


The value of Tm fora clockln frequency of 5MHz. 
This is computed from the other parameters and 
displayed. 


Wait states 


The number of wait states in the current configu- 
ration. This is computed from the other parame- 
ters and displayed. 


Standard configura- 
tion 


The parameters can all be reset to those for one 
of the built in configurations. There are 13 stan- 
dard configurations available for the T414, valid 
configuration numbers being to 11 and 31. For 
the T400, T425, T800 and the T805 there are 17 
standard configurations available, valid configu- 
ration numbers being to 15 and 31. If the user 
selects, fora T414, one of the four configurations 
which are not available, a message will be 
displayed indicating that this configuration may 
not be hardwired on a T414. 
If the currently set configuration happens to corre- 
spond exactly to one of the preset configurations, 
the tool reports the fact. 



Table 6.5 iemit page 1 parameters 
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6.4 Interactive operation 



6.4,3 Page 2 

This page shows general timing information for the interface, such as delays 
between various strobes and required access times of the memory devices to be 
used. The user should adjust these figures to allow for delays in external logic. 

Table 6.6 lists the timing information displayed on this page while an example of 
the display is given in figure 6.3. 



JEDEC 
symbol 


Parameter description 


TOLOL 


Cycle time (in both nanoseconds and processor cycles) 


TAVQV 


Address access time 


TOLQV 


Access time from notMemSQ 


TrLQV 


Access time from notMemRd 


TAVOL 


Address setup time 


TOLAX 


Address hold time 


TrHQX 


Read data hold time 


TrHQZ 


Read data turn off 


TOLOH 


notMemSQ puLse width low 


TOHOL 


notMemSO putse width high 


TrLrH 


notMemRd pulse width low 


TrLOH 


Effective notMemRd width 


TOLwL 


notMemSQ to notMemWrB delay 


TDVwL 


Write data setup time 


TwLDX 


Write data hold time 1 


TwHDX 


Write data hold time 2 


TwLwH 


Write pulse width 


TwLOH 


Effective notMemWrB width 



Table 6,6 General timing parameters 

The total cycle time is given in nanoseconds and in processor clock cycles. The 
only option available from this page is to select another page for display. 
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Page 2 



Symbol Parameter 



General Timing 



nitidis) max(ns) Notes 



TQLOL Cycle time 

TAVQV Address access time 

TOLQV Access time from 

TrLQV Access time from r 

TAV01 Address setup time 

TOLftX Address bold time 

TrHQX Read data hold time 

TrHQZ Read data turn off 

TQLOfl pulse width low 

TOHOL pulse width high 

TrLrH r pulse width low 

TrLOfl Effective r width 

TOLwL to w delay 

TDVwL Write data setup time 

TwLDX Write data hold time 1 

TwHDX Write data hold time 2 

TwLwH Write pulse width 

TwLOE Effective w width 

Please enter a new page niimher {0 



4SQ 



12 processor cycles 



- 


■ICC 


- 


32C 


- 


160 


so 


- 


so 


- 





- 




80 




- 


160 


- 


160 


- 


ISO 


- 


80 


- 


240 


- 


80 


- 


160 


_ 


160 


- 


for 


the index) 



Figure 6.3 Example iemit display page 2 



6.4.4 Page 3 



Page 3 



Symbol Parameter 



Dynamic RAM Timing 



T1LIH 1 pulse width 

T1H1L 1 precharge time 

T3L3H 3 pulse width 

T3H3L 3 precharge time 

T1L2L 1 to 2 delay 

T213L 2 to 3 delay 

T1L3L 1 to 3 delay 

tilqv Access time from 1 

T2LQV Access time from 2 

T3LQV Access time from 3 

T3L1E 1 hold (from 3} 

T1L3H 3 hold (from 1) 

TwL3H w to 3 lead time 

TwLlH w to 1 lead time 

TILwH w hold (from 1) 

T1LDX Wr data hold from 1 

T3HQZ Read data turn off 

TRFSH 256 refresh cycles 

^Please enter a new page number (Q 



mining) max(ns) Notes 

400 
80 



3?C 



240 
320 
400 



3650 
for the index) : 



time in microseconds 



Figure 6.4 Example iemit display page 3 

This page gives timing information of special interest to designers working with 
dynamic memory, including various access times and the time for 256 refresh 
cycles. With this information the designer can ensure that the requirements of the 
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6.4 Interactive operation 



memory devices to be used are met. The user should adjust these figures to allow 
for delays in external logic. Table 6.7 lists the DRAM timing parameters. 

The only option available from this page is to select another page for display. An 
example of the display is given in figure 6.4. 



JEDEC 
symbol 


Parameter description 


T1L1H 


notMemSI pulse width 


T1H1L 


notMemSI precharge time 


T3L3H 


notMemS3 pulse width 


T3H3L 


notMemS3 precharge time 


T1L2L 


notMemSI to notMemS2 delay 


T2L3L 


notMemS2 to notMemS3 delay 


T1L3L 


notMemSI to notMemS3 delay 


T1LQV 


Access time from notMemSI 


T2LQV 


Access t:n~i8 from notMemS2 


T3LQV 


Access time from notMemS3 


T3L1H 


notMemSI hold (from notMemS3) 


T1L3H 


notMemS3 hold (from notMemSI) 


TwL3H 


notMemWrB to notMemS3 lead time 


TwL1H 


notMemWrB to notMemSI lead time 


T1LwH 


notMemWrB hold (from notMemSI) 


T1LDX 


Write data hold from notMemSI 


T3HQZ 


Read data turn off 


TRFSH 


Time for 256 refresh cycles (in microseconds) 



Table 6.7 DRAM timing parameters 



6,4.5 Page 4 



This page shows graphically the timing for a memory read cycle. An example of 
the display page is given in figure 6.5. 

The Tstates and strobes are labelled, and bus activity is shown. The point where 
data are latched into the processor is also indicated. 

At the top of the page is displayed the processor clock and the Tstates, a number 
indicating the Tstate, W indicating a wait state, and 'E' indicating a state that is 
inserted to ensure that T1 starts on a rising edge of the processor clock. 
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Below this are displayed the waveforms of the programmable strobes and the 
read, write and address/data strobes. Each of these strobes is labelled with the 
corresponding label parameter 

The point at which the read data is latched is indicated by a w beneath the read 
cycle address/data strobe. 



ProcClock / 


\ 


/w\/w\/wwww\/w\ 


notMemSO 


(0) 




\ / 






notXemSl 


(I) 




\ 






notMemS2 


(2) 






notMemS3 


(3) 






notMemS4 


(4) 






MemWait 






\ 



READ CYCLE 
MemAD 



Read data latched here 



notMemRd (r) \_ 



Please enter a new page number (0 for the index) , <L> to 
scroll display left, or <R> to scroll display right: 

Figure 6.5 Example iemit display page 4 

The MemWait waveform shows the input to the MemWait pin. If the wait input is 
a number then it goes low n Tm periods after the end of Tl and high again at the 
end of T6, if the wait input is connected to a strobe it goes low and then high when 
that strobe does so. 

If the cycle is too long to fit horizontally on the screen, it may be scrolled left and 
right using the |T] and [W] keys. The displayed area moves by about 1 5 charac- 
ters each time these are used. 



6.4.6 Page 5 

Page 5 shows the waveforms for a memory write cycle. The display is similar to 
that of page 4, indeed the read and write cycle diagrams are combined when the 
PostScript output is produced. 

Scrolling the display to the left or right is done in the same way as for page 4. 

An example of the display page is given In figure 6.6. 
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' Page 5 

ProcClock 

notMemSO (0) 

notMemSl (1) 

notMemS2 (2) 

notMemSS (3) 

notMemS4 (4) 

MemWait 
WRITE CYCLE 
MetnftD 

notMeitiWrBl[w) 

Please enter 
scroll displ, 


|1|1|1|1|2]2|2|2|3|3S3|3|4|4|4|4|5|5|5J5|6|6|6|61 








\ / 






\ 




















X 




\ 




X 




\ / 

new page number (0 for the index) , <L> to 
left, or <R> to scroll display right: 



Figure 6.6 Example iemit display page 5 



6.4.7 Page 6 



This page gives a configuration table for the current configuration. This is a listing 
of the data which have to be placed in a ROM situated at the top of the transputer's 
memory map in order to achieve the desired configuration. The table consists of 
36 words of data, but only the least significant bit in each is used. The address and 
contents are given for each location. Note: when iemit is used to generate the 
memory configuration, the Memconfig pin must be connected to MemnotWrDO. 

An example of the display page is given in figure 6.7. 

Note: that if page 1 indicates that the configuration is one of the transputer's preset 
ones, there will be no need for a ROM; configuration can be achieved by 
connecting the MemConfig pin of the device to one of the address/data lines. 
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Page 6 



Configuration Table 



#7fffff6c 
*7fffff70 
*7fffff74 
#7fffff78 
*7fffff7c 
*7fffff80 
*7fffff84 
*7fffff88 
#7fffff8c 
#7fffff9C 
*7fffff94 
#7fffff98 
*7£ffff9c 
*7fffffa0 
#7fffffa4 
*7fffffa8 
*7fffffac 
#7fffffb0 
Please enter a new page number 



*7fffffb4 


r 1 


*7fffffb8 


1 


*7fffffbc 


: 


#7fffffcQ 


i 


#7fffffc4 


c 


#7fffffcfi 


l 


*7fffffCC 


i 


*7fffffd0 


l 


J7fffffd4 


l 


mffffdS 





|7fffffdc 


l 


#7ffff£e0 





*7fffffe4 





*7fffffe8 


1 


|7fffffec 


; 


#7ffffff0 


: 


titittzii 


: 


#7ffffff8 


l 


(0 for the index) 



Figure 6 J Example iemit display page 6 

6.5 iemit error and warning messages 

The following is a list of error and warning messages the tool can produce: 

Wait race 

If one of the programmable strobes is used to extend the memory cycle 
then the strobe must be taken low an even number of periods Tm after the 
start of the memory interface cycle. If the strobe is taken lowan odd number 
of periods after the start then a wait race warning will appear. Should this 
warning appear, it will remain on display on page 1 , until the race condition 
is removed. Further information can be obtained from reference 1, listed 
at the start of this chapter. 

Input out of range 

If the value entered for a numeric parameter Is outside the range valid for 
that parameter, an input out of range warning is displayed, the value 
cleared from the screen and the program waits for a new value. 

MemWait connection error 

If an attempt is made to connect S1 to the MemWait input an error is 
displayed because it is a meaningless operation. 

Configuration cannot be hardwired on a T414 

The transputers which have a configurable memory interface all have {with 
the exception of the T414) 17 standard memory configurations available 
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to them. The T414 only has a choice of 13 standard configurations. If the 
standard configurations 12, 13, 14 or 15 are selected for aT414the above 
warning message will be displayed against the selection on page 1 . 

Unable to open configuration file 'filename* 

This can occur when attempting to load a memory configuration file and 

indicates that the tool cannotfind the specified inputfile. Check the spelling 

of the filename and/or that the file is present- 
Command line parsing error 

An option has been specified that the tool does not recognize. 

No input file specified 

This indicates that when trying to invoke the tool to produce an output file, 
the user has not specified a memory configuration file to use as input 

One and only one of options A or P must be specified 

This indicates that when trying to produce an output file, the user has not 
specified whether the output is to be in ASCII or PostScript format. 

Unable to open output file filename' 

An output filename has been specified incorrectly. Check the format of the 
filename. 



6.6 Memory configuration file 

Memory configuration files are text files which may be generated by a standard text 
editor or by using the memory interface configuration tool iemit, see section 6.2. 

By convention memory configuration files have the file extension .mem. The file 
consists of a sequence of statements and comments. The following are consid- 
ered to be comments: 

* Blank lines 

* Any line whose first significant characters are ( — ' 

* Any portion of a line following ' — '. 

Comments are ignored by the ieprom and iemit tools. Statements are all other 
lines within the file; they may be interspersed with comments. 

Individual statements are constructed of the statement and an associated param- 
eter. These must be separated by at least one space or tab but extra spaces may 
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be inserted before, between, or after them for aesthetic purposes. An example 
memory configuration file is shown in figure 6.8. 



rz. 



Memory configuration file produced 
by a save command from IEMIT. 
on Thu Feb 13 15:04:04 1992 



device. type 


^ 


T425-25 


tl. duration 


= 


4 


t2 . duration 


= 


4 


t3. duration 


- 


i 


t4. duration 


= 


4 


t5. duration 


- 


i 


t6, duration 


- 


4 


sO. label 


= 


notMemSQ 


si. label 


= 


notMemSl 


32, label 


■- 


notMemS2 


s3. label 


--^ 


notMemS3 


s4, label 


= 


notMemS4 


rs. label 


. 


notMemitd 


wo. label 


= 


notMemWrB 


si. duration 


= 


30 


s 2. duration 


= 


30 


s3. duration 


= 


30 


s4. duration 


■ 


is 


refresh. period 


= 


12 


write. mode 


=-= 


LATE 


wait . connection 


- 






Figure 6.8 Example memory configuration file 

The statements defined are listed along with their parameters in table 6.8. Further 
information about specifying parameters is given in section 6.4.2. 



Option 


Description 


standard . configuration 


to 13, or 31 forT414 processors, to 15, or 




31 forT400, T425, T800 and T805 processors. 


device . type 


One of the following devices: 




T400-20 T800-17 




T414-15 T800-20 




T414-17 T800-22 




T414-20 T800-25 




T425-17 T800-30 




T425-20 T800-35 




T425-25 T800-25 




T425-30 T805-30 
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6.6 Memory configuration file 



Option 


Description 


tl. duration, 
t2 . duration , 
t3. duration, 
t4 .duration, 
t5. duration, 
t 6. duration 


1 to 4 Tm periods. {2 Tm periods = 1 clock 
cycle). Defines the length in Tm periods of 
Tstates, T1 to T6, of the memory cycle. 


sO .label, 
si, label, 
s2. label, 
s3. label, 
s4. label 


Each of these parameters accepts two text 
strings. They are the long (up to 9 characters) 
and short (1 character) names of the strobes 
notMemSO to notMemS4. The names should 
not contain embedded spaces. Names longer 
than the permitted number of characters will be 
truncated. 


rs . label 


As above, the long and short names for the 
read strobe notMemRd. 


ws . label 


As above, the long and short names for the 
read strobe notMemWrB. 


si .duration 


to 31 Tm periods. The S1 strobe goes low at 
the start of Tstate 2. This parameters defines 
the number of Tm periods before it goes high. 


s2. duration, 
s3. duration, 
s4 .duration 


to 31 Tm periods. The S2 to S4 strobes all go 
high at the end of Tstate 5. These parameters 
define the number of Tm periods before each 
strobe goes low. 


refresh. period 


18, 36, 54, 72 or the string "Disabled". This 
parameter defines the period between refresh 
cycles as a count of Clockln cycles. 


write, mode 


String value either 'Early" or "Late". Defines 
the write mode. 


wait . connection 


S2, S3, S4 or a value in the range to 60. This 
parameter connects MemWait to one of the 
strobes S2, S3, S4 or to simulated external wait 
state generator. 



Table 6.8 Memory Configuration file statements 
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This chapter describes the EPROM hex tool ieprora. This tool is used to convert 
a ROM-bootable file into one or more files suitable for programming an EPROM. 

The chapter describes how to invoke ieprom and gives details of the command 
line syntax. It describes the control file which the tool accepts as input and provides 
background information on the layout of the code in the EPROM. A description of 
the various file formats which may be output by the tool is given, including block 
mode where the output is split up over a number of files. The chapter ends with a 
list of error messages which may be generated by the tool. 



7.1 Introduction 

The INMOS EPROM software is designed so that programs which have been 
developed and tested as boot-from-link programs, using the INMOS toolset may 
be placed in ROM with only minor modification (see below). 

This has the advantages that an application need not be committed to ROM until 
it is fully debugged and the actual production of the ROMs can be done relatively 
late in the development cycle without the fear of introducing new problems. 

If a network of transputers is being used, only the root transputer needs to be 
booted from ROM; once this has been booted it will boot its neighbors by link. 

Figure 7.1 shows how a network of five transputers would be loaded from a ROM 
accessed by the root transputer. 



















Boot from link 








. 












ROM »=$^* 


Root transputer 
boot from ROM 


*■ 


Boot from link 


— ■- 


Boot from link 






,. i 


' 














Boot from link 



















Figure 7.1 Loading a network from ROM 
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7.2 Prerequisites to using the iepromtool 



Some 32 bit transputers have a configurable external memory interface. For these 
transputers a memory configuration file may be created and put into ROM together 
with the application. A description of memory configuration files and how to create 
them is given in Chapter 6. 



7.2 Prerequisites to using the ieprom tool 

For an application file to be suitable for programming into ROM it must have been 
configured to be booted from ROM rather than booted from link. This selection is 
made by specifying the appropriate command line option when using the confi- 
gurer and collector tools (see the relevant chapters of this manual). It is also essen- 
tial that all C and FORTRAN programs, including those targeted at a single 
processor, are configured. C and FORTRAN programs prepared with the 
icollect 'T' option are not in a format suitable for ieprom. 



7.3 Running ieprom 

ieprom takes as input a control file and outputs one or more files which may be 
put into ROM by an EPROM programmer. 

The control file, in text format, specifies the root transputer type, the name of the 
bootable file containing the application, the memory configuration file (if one is 
being used), the amount of space available in the EPROM, and the format that the 
output is to take. Available output formats are: binary, hex dump, Intel, Extended 
Intel, or Motorola S-Record format. 

The iepromtool is invoked by the following Gommand line; 
P* ieprom filename { options } 
where: filename is the name of the control file. 
options is a list of options from Table 7.1. 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 
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Option 


Description 


i 


Selects verbose mode. In this mode the user will receive status 
information about what the toot is doing during its operation, for 
example reading or writing to a file. 


R 


Directs ieprom to display the absolute address of the code 
reference point. This address can be used to locate within the 
memory map created by the icoliect 'p' option. 



Table 7. 1 ieprom command line options 
The operation of ieprom In terms of standard file extensions is shown below. 







7 .bin J 


.ihxj 

.mot) 


ieprom 


i .t,pr j ^ 





7.3.1 Examples of use 

ieprom may be invoked in verbose mode by using one of the following commands: 
ieprom -i mycontrol.epr (UNIX based toolsets) 

ieprom /i mycontrol.epr (MS-DOS and VMS based toolsets) 

7.4 ieprom control file 

The control file is a standard text file, prepared with an editor; it consists of 
comments and statements. A comment is any blank line or any text following the 
comment marker ' — '. Comments are ignored by the ieprom tool. 

Statements are all other lines within the file. They may be in any order, except that 
the four statements defining a block must immediately follow the statement 
'output. block' (see table 7.3). Statements may be interspersed with 
comments. 

Individual statements are constructed of a keyword and an associated parameter. 
These must be separated by at least one space or tab but extra spaces may be 
inserted before, between, or after them for aesthetic purposes. The statements are 
listed, along with their parameters, in tables 7.2 to 7.4. 

Examples of control file contents are given in section 7.8. 
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7.4 ieprom control file 



The statements in table 7.2 are used to specify the contents of the EPROM: the 
processor type, the source of the data (code and memory configuration) to be 
placed in the EPROM, and the total size of EPROM memory. 



Statement 


Parameter/Description 


root . processor . type 


type 

This statement specifies the processor type. The 
processor type can be specified in full (e.g. T400), 
or one of the following classes can be specified: 

T2: 16 bit processor (M212, T212, T222, T225) 

T4: 32 bit processor (T400, T414, T425, not T426) 

T8: 32 bit processorwith FPU (T800, T801, T805) 

The IMS T426 must be specified as T426. See 
appendix B for a full List of valid processor types. 

This statement must be present as the first line in 
the control file. 


bootable . file 


filename 

This statement specifies the file that contains the 
output of icollect, usually the application plus 
its ROM loaders). 

This statement must be present in the control file. 


memory. configuration 


filename 

This statement specifies a T4/T8 memory configu- 
ration file to be included in the EPROM image. This 
file is a standard memory configuration description 
(see chapter 6 for details). 

This statement is optional. If absent from the 
control file then no memory configuration wiil be 
inserted in the output file. 


eprom. space 


hex number 

This statement specifies the size of the EPROM 
memory space in bytes. This space may actually 
contain several physical devices. 

This statement must be present in the control file. 



Table 7.2 Specifying the EPROM contents 
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The statements in table 7.3 specify the output to be produced: the format of the 
data and whether the data Is to be placed in a single file or split into blocks. 



Statement 


Parameter/Description 


output . format 


hex | Intel | extintel | srecord [ binary 

This statement specifies the output file format as being one 
of: plain ASCII hex, Intel hex, extended Intel hex, Motorola 
S-record or binary format respectively. These output formats 
are explained in section 7.6. 

This statement is optional. If absent from the control file then 
the default output is hex. 


output . all 
output. block 


filename 

filename 

These statements are used to specify the type of output and 
the output filename. By convention the following file exten- 
sions should be used: 

. hex Hexadecimal 
.bin Binary 
. ihx Intel formats 
. mot Motorola format 

output . all means that all of the image is to be output to 
one file. 

output . block specifies that a block of data is to be output 
to the specified file. It must be followed by the four statements 
that define the block; these are detailed in table 7.4. 

The control file must contain one output, all statement, or 
one or more output-block statements. 



Table 7.3 Specifying the output format 

Table 7.4 lists the statements used to define each output block. One of each of 
these statements must follow each output .block statement. 
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7.5 What goes into the EPROM 



Statement 


Parameter/Description 


start. off set 


hex number 

This statement specifies the address of the start of the 
block, as a byte offset into the EPROM space. 


end. offset 


hex number 

This statement specifies the address of the end of the 
block, as a byte offset into the EPROM space. 


byte. select 


byte //s/ 1 all 

This statement is followed by either a list of byte numbers 
(separated by &), or the keyword all. It specifies which 
bytes in a word are to be output in this block. The byte 
numberecan be 0, l^andS for32bit processors; or G and 
1 for 16 bit processors. 


output . address 


hex number 

This statement specifies the byte address, in the EPROM 
programmer's memory map, at which the block is to be 
output. 



Table 7.4 Output block specification 



7.5 What goes into the EPROM 

This section describes the contents of the EPROM, the reasons behind the code 
layout and the function of those components inserted by ieprom. 

The contents of the EPROM includes the bootable file, traceback data and jump 
instructions to enable the processor to find the start of the bootable file. Should the 
user define the memory configuration this information will also be placed in the 
EPROM. The general layout of the code in the EPROM is shown in figure 7.2. 



7.5.1 Memory configuration data 

Memory configuration data, when present, is placed immediately below the top 
word of the EPROM. The top word holds the first instructions to be executed if the 
transputer is booting from ROM. 

If the processor has a configurable memory interface it will scan the memory 
configuration data held on the EPROM, before executing the first instructions. If 
a standard memory configuration is being used there should be no memory config- 
uration data present and the processor will ignore this section of the EPROM. 
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« 1 


Address (T4/T8) Address (T2) 
#7FFFFFFE #7FFE 

F 

#7FFFFF60 (T426) # 7FFA 

#7FFFFF68 (others) 

r 

n 

increasing address 




jump to bounce 


data from memory 
configuration file 
{T4 and T8 only) 


parity registers 
(T426orilyj 


bounce jump 


content of bootable 
file minus icollect 
comment bootstrap 


trace back information 




empty 



Figure 7.2 Layout of code in EPROM 



7.5.2 Parity registers 

The T426 has the Parity ErrorReg and ParityErrorAddressReg mapped into the 
two words immediately below the memory configuration data (addresses 
#7FFFFF64 and #7FFFFF68). The EPROM tool needs to know that it must avoid 
these addresses on the T426 and so the processor type must be given explicitly 
in the root.processor.type statement. 



7.5.3 Jump instructions 

The first instruction executed by the processor when booting from EPROM, is 
located at most positive integer- 1: this is #7FFFFFFE for 32-bit machines and 
#7FFE for 1 6-bit machines. The first two instructions cause a backwards jump to 
be made, with a distance of up to 256 bytes; however, since most applications are 
larger than 256 bytes it is necessary for ieprom to insert a 'bounce' jump back to 
the start of the bootable file. 
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7.5.4 Bootable file 

The bootable file will have been produced by the collector tool icoliect, using 
a boot from ROM loader. The comment bootstrap, containing traceback Informa- 
tion originally added to this file by icoliect, is stripped off by ieprom. 

The bootable file is placed in the EPROM such that the start of the file is placed 
at the lowest address, with the rest of the tile being loaded in increasing address 
locations. The end of the file is placed immediately below the bounce jump instruc- 
tion, which points to the start of the bootable file. 

7.5.5 Traceback information 

ieprom creates its own traceback information consisting of the name of the control 
file and the time at which ieprom ran. This information is placed below the start 
of the bootable file. Note: at present this information is not used by any of the toots. 

7.6 ieprom output files 

The tool can produce output in a form readable by the user or in a form readable 
by EPROM programming devices. The following formats are supported: 

• Binary output 

• Hex dump 

• Intel hex format 

• Intel extended hex format 

• Motorola S-record format 

Whichever form is used, it is sometimes necessary to output the data in separate 
blocks. Block mode operation is discussed in section 7.7. 

Note: there is no output for unused areas of the EPROM. If the buffer in the 
EPROM programmer is not initialized before loading the files produced by this 
program into it, unused areas of the EPROM will be filled with random data. 
Although the operation of the bootstrap code and loader programs will not be 
affected by the presence of random data, these areas of the EPROM cannot 
subsequently be programmed without erasing the whole device. 

7.6.1 Binary output 

This file is in binary format and simply contains all bytes output. There is no addi- 
tional information such as address or checksums. 

7.6.2 Hex dump 

This simple format is intended to be used to check the output from the program. 
The dump consists of rows of 16 bytes each, prefixed by the address of the first 
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byte of each raw. The format contains no characters other than the hexadecimal 
digits, the space character and newlines. 

7.6.3 Intel hex format 

This is a commonly used protocol for EPROM programming equipment. A 
sequence of data records is sent. Each record contains a few bytes of information, 
a start address and a checksum. In addition, a special record marks the end of a 
transmission. Since the format only supports 16-bit addresses, any longer 
addresses will generate an error message. Records produced by this program 
contain at most 32 bytes each. 

7-6.4 Intel extended hex format 

This format, also known as Intel 86 format, is similar to Intel hex, but adds another 
type of record. The new type 02 record is used to specify addresses of more than 
16 bits. The type 02 record contains a 1 6-bit field giving a segment base offset. This 
value is shifted left four places and added to subsequent addresses. This mimics 
the operation of the segment registers on the Intel 8086 range of microprocessors. 
The segment base offset value persists until the next type 02 record occurs. This 
format therefore allows addresses up to 20 bits in length. Again, longer addresses 
will generate an error message. The program minjmizes the number of type 02 
records inserted in its output. 

7.6.5 Motorola S-record format 

This format is another well known industry standard; it consists of a header record, 
data records, and finally an image end record. The advantage of this format is that, 
by the use of different data record types, it can support 16, 24, or 32 bit addresses. 
This program uses whichever data record type is necessary. 



7.7 Block mode 

Block mode is a term used to describe the output from ieprom, when more than 
one output file is produced. The user defines how the data is to be split between 
files using control file statements (see table 7.4). 

7.7.1 Memory organization 

In order to understand the ideas behind block mode operation it is helpful to under- 
stand the way memory is organized in a 16 or 32 bit transputer 

In general, a transputer with a 32 bit data bus will expect to read from memory in 
32 bit words; the addresses of these words will be on word boundaries (i.e. the 
address will always be divisible by4, the two least significant bits will be 0). EPROM 
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devices, however, are usually 8 bits wide, and so it is necessary to have 4 EPROMs 
side by side to make up the 32 bit width. These 4 devices are addressed as bytes 
to 3. The two least significant bits of an address (the 'byte selector 1 ) give the byte 
numbers. 

Similarly a 16 bit transputer will expect to read from memory in 16 bit words. The 
address of each word will always be divisible by 2. The two EPROM devices 
required to make up the 16 bit width will be addressed as bytes and 1 . In this case 
the least significant bit of an address indicates the byte being accessed. 



7.7.2 When to use block mode 

Block mode has three uses: 

• When the EPROM programmer being used is unable to split the input data 
into bytes, in order to program separate byte wide devices, 

• When the EPROM programmer has insufficient memory to hold the entire 
image, 

• When it is necessary, for some reason, to load the program to a different 
address in the EPROM programmer to that which it will occupy in the 
EPROM space. 

7.7.3 How to use block mode 

When block mode is to be used, the user must first decide on the blocks to be 
output. For each block an output. block statement must be specified in the 
control file. Each output .block statement must be followed by the four state- 
ments: 

start. offset 
end. offset 
byte . select 
output . address 

ieprom will scan the entire image and output those bytes that have an EPROM 
space address between start, off set and end .offset and whose byte 
address matches the byte . select value. It will output this data to contiguous 
addresses starting at output . address. 

Note: if the image does not occupy all of the EPROM space then there may be 
some space at output. address before the data starts. 
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7.8 Example control files 

7.8.1 Simple output 

For this example the application is in the file bootable , btr, there is no memory 
configuration, there is 128 kbytes of EPROM, and the EPROM programmer can 
take all of the code as one file. 

— EPROM description file for example 1 
root . proces sor . type T4 

bootable . file bootable . btr 

eprom . space 20000 

output . format srecord 

output, all image, mot 

7.8.2 Using block mode 

In this example the application is in embedded, btr, there is a memory configura- 
tion in fastsram.mem, there are 16 kbytes of EPROM and the data is to be split 
into four blocks of 4k EPROMs to be programmed at locations 0000, 1000, 2000, 
and 3000 in the EPROM programmer's memory. 

— EPROM description file example 2 

root . processor . type T8 
bootable . file embedded . btr 
memory . configuration fastsram.mem 
eprom. space 4000 

output . format intel 



output. block 


parti . ihx 


start. off set 


0000 


end. off set 


3FFF 


byte . select 






output . address 0000 

output . block part2 . ihx 

start, offset 0000 
end. off set 3FFF 
byte . select 1 
output . address 1000 

output . block par t3 . ihx 
start. offset 0000 
end . o f f set 3FFF 
byte. select 2 
output. address 2000 

output. block parti .ihx 
start. offset 0000 
end. off set 3FFF 
byte, select 3 
output. address 3000 
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7.9 Error and warning messages 

The following is a list of error and warning messages the tool can produce: 

Command line parsing error 

This indicates that a command line option has been specified that the tool 
does not recognize. 

Control file error 

This message wilf be received whenever an error is found in the format of 
the control Hie. A self explanatory message will be appended, giving details 
of what the tooi expects the format to be. 

No input file specified 

This indicates that when trying to invoke the tool the user has not specified 
a control file to use as input. 

Unable to open bootable file 'filename' 

The bootable file specified in the control file cannot be found. Check the 
spelling of the filename and/or that the file is present 

Unable to open configuration file filename' 

The memory configuration file specified in the control file cannot be found. 
Check the spelling of the filename and/or that the file is present. 

Unable to open control file 'filename' 

The control file specified cannot be found. Check the spelling of the file- 
name and/or that the file is present. 

Unable to open output fife filename' 

An output filename has been specified incorrectly. Check the format of the 
filename. 
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This chapter describes the librarian tool ilibr that integrates a group of compiled 
code files into a single unit that can be referenced by a program. The chapter 
begins by describing the command line syntax, goes on to describe some aspects 
of toolset libraries, and ends with some hints about how to build efficient libraries 
from separate modules. 

8.1 Introduction 

The librarian builds libraries from one or more separately compiled units supplied 
as input files. The input files may be any of the following: 

• Compiled object code files produced by the INMOS compilers: 

- oc (occam 2 compiler), 

- ice (ANSI C compiler), 

- if 77 (FORTRAN-77 compiler). 

• Library files already generated by ilibr (see section 8.2.4). 

• Linked object files (see section 8.2,3). 

The librarian takes a list of compiled files in TCOFF format and integrates them Into 
a single object file that can be used by a program or program module. Each module 
in the input list becomes a selectively loadable module in the library. Input files can 
either be specified as a list on the command line or in indirect files. 

The library, once built, will contain an index followed by the concatenated modules. 
The index is generated and sorted by the librarian to facilitate rapid access of the 
library content by the other tools in the toolset, for example, the linker. 

Compiled object files (excluding library files) may be concatenated for conve- 
nience before using the librarian. This may prove useful when dealing with a large 
number of input files. 

The operation of the librarian in terms of standard file extensions is shown below. 
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8.2 Running the librarian 

To Invoke the librarian use the following command line: 

► ilibr filenames {options} 
where: filenames is a list of input files separated by spaces. 
options is a list of one or more options from Table 8.1. 



Options must be preceded by '- for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 



The number of file names allowed on a command line is system dependent. To 
avoid overflow, files may be concatenated or an indirect file used. It is the user's 
responsibility to ensure that the concatenation process does not corrupt the 
modules, for example by omitting to specify that the concatenation is to be done 
in binary mode. 

If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Option 


Description 


F filename 


Specifies a library indirect file. 


I 


Displays progress information as the library is built. 


fiiename 


Specifies an output file. If no output file is specified the name is 
taken from the first input file and a . lib extension is added. 



Table 8.1 ilibr command line options 
Example 

ilibr myprog,t4x myprog.t8x 

In this example, the compiled object code files myprog. t4x and myprog, t8x 
(compiled for T4 and T8 transputers respectively) are used to create a library. 
Because no output file name is specified on the command line, the library will be 
given the name myprog, lib. 

8.2.1 Default command line 

A set of default command line options can be defined for the tool using the 
ilibrarg environment variable. Options must be specified in the variable using 
the syntax required by the command line. 
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8.2.2 Library indirect files 

Library indirect files are text files that contain lists of input files, directives to the 
librarian, and comments. Filenames and directives must appear on different lines. 
Comments must be preceded by the double dash character sequence ' — ', which 
causes the rest of the line to be ignored. By convention indirect files are given the 
. lbb extension. 

indirect files may be nested within each other, to any level. This is achieved by 
using the # INCLUDE directive. By convention nested indirect files are also given 
the extension . lbb. 

The following is an example of an indirect file: 
~ user's .lbb file 

userprocl . too — single modules 

userproc2 . tco 

userproc3 . tco 

myconcat . tco — concatenation of modules 

#INCLUDE indirect. lbb — another indirect file 

userproc4 . tco — another single module 

The contents of a nested indirect file will effectively be expanded at the position it 
occurred. 

To specify indirect files on the command line each indirect filename must be 
preceded by the 'f' option. 

8.2.3 Linked object input files 

The librarian will also accept linked object files as input, with certain conditions. The 
facility to create libraries of linked modules provides an easy method of specifying 
input to the configurer. Such library files should only be referenced from a configu- 
ration description. 

The librarian will generate an error if an attempt is made to include both linked units 
and compiled modules in a single library. In addition, libraries of linked object 
modules must not be used as input to the linker ilink. This is because the linker 
does not accept linked units as input files. 

8.2.4 Library files as input 

Library files can themselves be used as input files to ilibr. When a library file is 
used as a component of a new library, its index is discarded by ilibr. 

Library files may not be concatenated for input to the librarian. 

8.3 Library modules 

Libraries are made up of one or more selectively loadable modules. A module is 
the smallest unit of a library that can be loaded separately. Modules are selected 
via the library index. 
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8.3.1 Selective loading 

Libraries can contai n the same routines compiled for different transputer types and 
(for occam modules) in different error modes. 

Selection of library modules for linking in with the program is made on the basis 
of target processor type and error mode. For example, if the program is compiled 
for an IMS T414 only modules compiled for this processor type or for processors 
in a compatible transputer class are loaded. For languages such as FO RTRAN and 
C the error mode is always UNIVERSAL. 

For C and FORTRAN modules the linker selects the library modules best suited 
to the compilation units. For Occam the compiler identifies the modules to be 
selected according to the requirements of the main program. The linker then 
makes the selection. 

The linker also selects library modulesfor linking on the basis of usage. Only those 
modules that are actually used by the program are linked into the program. 

8.3.2 How the librarian sorts the library index 

The librarian creates a library index which is used by the Linker to select the 
required modules. The librarian sorts the index so that for a given processor type, 
the optimum module is always selected by the linker. 

The librarian compares and sorts modules according to a number of factors 
including attributes set by the compiler options used. These determine for 
example, the instruction set of the module and influence run-time execution times. 

For example, where two library modules were derived from the same source but 
compiled for classes TA and T4, the librarian would place the T4 module first 
because it uses a larger instruction set Modules compiled with interactive debug- 
ging enabled are placed later in the index than those for which debugging is 
disabled. The librarian orders the index entries such that the first valid entry is 
always the 'best choice'. If two entries are found to be identical the librarian will 
issue a warning. 

8.4 Library usage files 

Library usage files describe the dependencies of a library on other libraries or 
separately compiled code. They consist of a list of separately compiled units or 
libraries referenced within a particular library. The . liu files required by the tool- 
set's libraries are supplied by INMOS. 

If the imakef tool is used then library usage files should be created for all libraries 
that are supplied without source. This is to enable the imakef tool to generate the 
necessary commands for linking. Library usage files are text files. They may be 
created for a specific library by invoking the imakef tool and specifying a . liu 
target. See section 11 .5. 
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Such files are given the same name as the library file to which they relate but with 
an . liu extension. 



8.5 Building libraries 

This section describes the rules that govern the construction of libraries and 
contains some hints for building and optimizing libraries. 

8.5.1 Rules for constructing libraries 

1 . Routines of the same name in a library must be compiled for different trans- 
puter types, error modes or debug attributes. 

2. Libraries that contain modules compiled for a transputer class (I.e. TA or 
TB) are treated as though they contain a copyfor each member of the class 
{using the subset of instructions which are common), 

3. Libraries that contain modules compiled in UNIVERSAL mode are treated 
as though they contain a copy for each of the two error modes HALT and 
STOP. 

4. Libraries that contain modules with interactive debugging enabled are 
treated as though they also contain a copy with interactive debugging 
disabled. (When interactive debugging is enabled, channel input/output is 
performed via library calls otherwise transputer instructions are used). 

8.5.2 General hints for building libraries 

Routines that are likely to be used together in a program or procedure (such as 
routines for accessing the file system) can be incorporated into the same library. 
At a lower level, routines that will always be used together (such as those for 
opening and closing files) can be incorporated into the same module. 

Libraries can contain the same routines compiled for different transputer types, in 
different error modes and with different input/output access to channels. Only 
those modules actually used by the program are incorporated by the compiler and 
linked in by the linker. 

Where possible compile library input files with debugging enabled. This enables 
the debugger to locate the library source if an error occurs inside the library. 

When building C libraries care should betaken if the 'FS' or 'FC' INMOS C compiler 
command line options are used, that code compatibility is maintained. 

8.5.3 Optimizing libraries 

It is possible for the user to optimize the size and content of any libraries which he 
builds himself, to target appropriate processors, improve the speed of code execu- 
tion and to provide the best code for a given processor. 
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ATI libraries 

Points to consider when constructing libraries in any language or mixture of 
languages: 

• Whether the library is to be targeted at one or two specific processors or 
a wide range of processors. The transputer type specified for the compila- 
tion of a library module determines the Instruction set used. Transputer 
classes TA and TB provide the basic instruction sets common to several 
transputer types. Transputer classes such as the T5 provide extended 
instruction sets but are targetted at fewer transputers than classes TA and 
TB. 

• For floating point operations, classes T5 and TB provide better code and 
therefore better execution times than class TA. 

• Whether the versatility of the library should be reduced in order to create 
a smaller library. 

Libraries containing occam modules 

When building libraries which include modules written in occam the same consid- 
erations apply, but also note the following: 

• The error mode used will affect the size of the library. A library created from 
modules compiled in UNIVERSAL mode will behave as if it contains a copy 
of the code for both HALT and STOP mode. Also, on the current range of 
transputers, code compiled in HALT mode will tend to execute faster than 
if it is compiled in STOP or UNIVERSAL error modes. 

• For libraries containing modules where the method of channel input/output 
may be altered, (such as in Occam), both the availability of the interactive 
debugging facility and the speed at which the code will be executed may 
be affected. 

When interactive debugging is enabled, channel input/output will be imple- 
mented via library calls. When interactive debugging is disabled using the 
compiler T option, transputer instructions are used for channel input/ 
output This leads to faster execution times. However, disabling interactive 
debugging for one module of a program, will disable this facility for the 
whole program. 

For a detailed description of transputer types and error modes, see appendix B. 

Outlined below are three different approaches to optimization. The first approach 
provides the greatest level of flexibility in Its application. The experienced user may 
refine these guidelines to specific requirements. 

Semi-optimized library build targeted at all transputer types 

This is the simplest way to build a library that covers the full range of transputers. 
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The user should compile each module separately for the following three cases and 
incorporate all three versions into the library. 



Processor type/class 


Error mode 


Method of channel I/O 


T2 


UNIVERSAL 


Via library calls 


TA 


UNIVERSAL 


Via library calls. 


T8 


UNIVERSAL 


Via library calls. 


Note: Error mode and channel i/o only apply only to modules which employ them 
e.g. Occam modules compiled by oc. 



The resulting library will be small in terms of the number of modules it will contain. 
Due to their generic nature the modules themselves may be bulky and because 
they contain only the base set of instructions, the execution time for the program 
will tend to be slower than a more optimized approach. 

Optimized library targeted at all transputer types 

In order to build a library which is both generalized enough to work for all 32-bit 
transputers and is then optimized for modules which require extended instructions 
sets the following approach is recommended: 

1. Compile all modules for classes TA and T8. This will provide modules which 
can be run on all 32-bit transputers. 

2. If any of the modules perform floating point operations, compile these 
modules for class TB as well. 

For 16-blt transputers it should be sufficient to compile all modules for class T2. 

Library build targeted at specific transputer types 

This method of building a library will limit the use of the library modules to specific 
transputer types and error modes. It is recommended as the simplest strategy to 
use when the following options are known for each module: 

• Target transputer type. 

• Error mode of modules, rf any, (i.e. HALT, STOP or UNIVERSAL). 

• Method of channel input/output, if any. 

All modules to be included in the library must be compiled for each target transputer 
type and, if appropriate, for the same error mode and method of channel input/ 
output. The resulting library may be large and contain a certain amount of duplica- 
tion. 

For example, for the following options: 
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• T414 and T425 processor types 

• HALT error mode 

• channel input/output via library calls 
each module should be compiled for the following: 



Processor type/class 


Error mode 


Method of channel I/O 


T414 


HALT 


Via library calls 


T425 


HALT 


Via library calls. 


Note: Error mode and channel i/o only apply only to modules which employ them 
e.g. occam modules compiled by oc. 



8.6 Error Messages 

This section lists each error and warning message which may be generated by the 
librarian. Messages are in the standard toolset format which is explained in 
appendix A. 



8.6.1 Warning messages 

filename - bad format: symbol symbol multiply exported 

An identical symbol has occurred in the same file. There are three possibili- 
ties: 

The same file has been specified twice. 

The file was a library where previous warnings have been ignored. 

A module in the file has been incorrectly generated. 

filenamel - symbol symbol also exported by filename2 

An identical symbol has occurred in more than one module. If the linker 
requires this symbol, it wilt never load the second module, 

8.6.2 Serious errors 

bad format: reason 

A module has been supplied to the librarian which does not conform to a 
recognized INMOS file format or has been corrupted. 
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Filename - line number- bad format: excessively long line in indirect file 

A fine is too long. The length is implementation dependent, but on all 
currently supported hosts, is long enough to only be exceeded in error. 

filename - line number -bad format: tile name missing after directive 

A directive (such as include) has no file name as an argument. 

filename - line number- bad format: non ASCII character in indirect file 

The indirect file contains some non printable text. A common mistake is to 
specify a library or module with the f command line argument or the 
include directive. 

bad format: not a TCOFF file 

The supplied file is not a library or module of any known type. 
filename - line number- bad format: only single parameter for directive 

The directive has been given too many parameters. 
command tine error token 

An unrecognized token was found on the command line. 
filename - could not open for reading 

The named file could not be found/opened for reading. 
filenamel - fine number- could not open Fiiename2 for reading 

The file name specified in an include directive could not opened. 
filename - could not open for writing 

The named file could not be opened for writing. 

filename - must not mix linked and linkable files 

The librarian is capable of creating libraries from compiled modules or 
linked units, but it is illegal to attempt to create a library from both. 

no files supplied 

Options have been given to the librarian but no modules or libraries. 

filename - nothing of importance in file 

The file name specified in a library indirect file or in an INCLUDE directive 
was empty or contained nothing but white space or comments. 
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filename - line number - only one file name per tine 

More than one file name has been placed on a single line within an indirect 
file. 

filename - fine number- unrecognised directive directive 

An unrecognized directive has been found in an indirect file. 
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This chapter describes the linker tool ilink which combines a number of 
compiled modules and libraries into a linked object file. The chapter begins with 
a short introduction to the linker, explains the command line syntax and goes on 
to describe linker indirect files and the main linker options. The chapter ends with 
a list of linker messages. 



9.1 Introduction 

The linker links a number of compiled modules and library files into a single linked 
object file (known as a linked unit), resolving a)! external references. The linker may 
be used to link object files produced by the ANSI C compiler ice, the occam 2 
compiler oc, and the FORTRAN-77 compiler if 77. Code produced by the linker 
can be used as input to the configurer and collector tools to produce a bootable 
code file. 

The linker can be driven directly from the command line or indirectly from a tinker 
indirect file. This is a text file which contains a list of files to be linked, together with 
directives to the linker. 

The linker is designed to accept input files in the Transputer Common Object File 
Format (TCOFF) supported by this release of the toolset. However, the linker can 
be directed to produce output files in tinker File Format (LFF), In this format the 
output is compatible with either the iboot or iconf tools used by previous 2 
INMOS toolset releases. 

The operation of the linker in terms of standard toolset file extensions is shown 
below. 



®. 






Ltco) - 


ilink 


-Uku) 




@ 





2. Pre-TCOFF toolsets, for example the Dx05 Occam toolsets. 
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9.2 Running the linker 

To invoke the linker use the following command line: 

► ilink [filenames] {options} 
where: filenames is a list of compiled files or library files. 
options is a list of the options given in Table 9.1. 



Options must be preceded by ■-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 

If an error occurs during the linking operation no output files are produced. 

Example of use: 

UNIX based toolsets: 

ice hello 

ilinfc hello. tco -f cstartup.lnk 

icconf hello. cfs 
icollect hello. cfb 
Iserver -sb hello, btl -se 

MS-DOS and VMS based toolsets: 

ice hello 

ilinJc hello. tco /f cstartup.lnk 

icconf hello. cfs 
icollect hello. cfb 
iserver /sb hello. btl /se 

In this example a compiled C file is linked for the default T414 transputer, using the 
standard C startup linker indirect file cstartup . Ink. The example also shows 
the steps for compiling, booting and loading the program. 
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Option 


Description 


Transputer type 


See appendix B for a list of options to specify transputer type . 


EX 


Allows the extraction of modules without linking them. See 
section 9.5.4. 


F filename 


Specifies a linker indirect file. 


H 


Generates the linked unit in HALT mode. This is the default 
mode for the linker and may be omitted for HALT mode 
programs. This option is mutually exclusive with the 's J 
option. 


I 


Displays progress information as the linking proceeds. 


kb memorysize 


Specifies virtual memory required in Kilobytes. 


LB 


Specifies that the output is to be generated in LFF format, for 
use with the iboot bootstrap tool and iconf configurer tool 
used in earlier INMOS toolsets. (Pre-TCOFF toolsets e.g. 
the Dx05 occam toolset). 


LC 


Specifies that the output is to be generated in LFF format, for 
use with the iconf tool used in earlier INMOS toolsets. (Pre- 
TCOFF toolsets e.g. the Dx05 occam toolset). 


ME entryname 


Specifies the name of the main entry point of the program and 
is equivalent to the #mainentry linker directive (See 9.4.4). 


MO filename 


Generates a module information file with the specified name. 


filename 


Specifies an output file. 


s 


Generates the linked unit in STOP mode. This option Is mutu- 
ally exclusive with the 'H' option. 


T 


Specifies that the output is to be generated in TCOFF format. 
This format is the default format. 


U 


Allows unresolved references. 


X 


Generates the linked unit in UNIVERSAL error mode, which 
can be mixed with HALT and STOP modes. 


Y 


Disables interactive debugging for Occam code. Used when 
linking in occam modules compiled with interactive debug- 
ging disabled. 



Table 9.1 ilink command line options 

9.Z1 Default command line 

A set of default command line options can be defined for the tool using the ILIK- 
KflRG environment variable. Options must be specified using the syntax required 
by the command line. 

9.3 Linker indirect files 

Linker indirect files are text files containing lists of input files and commands to the 
linker Indirect files are specified on the command line using the 'F' option. 
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Linker indirect files can contain filenames, linker directives, and comments. File- 
names and directives must be on separate lines. Comment lines are introduced 
by the double dash (' — ') character sequence and extend to the end of line. 
Comments must occupy a single line. 

Indirect files can include other indirect files. 

Linker indirect files must be created for all link operations which involve the use of 
imakef and either C or FORTRAN modules. For further details see section 1 1 .4. 



9.3.1 Linker indirect files supplied with the toolset 

Linker indirect files supplied with the toolset are described in section 3.11 of the 
Toolset User Guide. The purpose of these files is to reference various runtime 
libraries (or in the case of Occam, compiler libraries) required to link application 
programs. When specifying the program modules to be linked, the appropriate 
linker indirect file must be included on the linker command line. 



9.4 Linker directives 

The linker supports six directives which can be used to fine tune the linking opera- 
tion. Linker directives must be incorporated in indirect files (they cannot be speci- 
fied on the linker command line) and are introduced by the hash ('#') character. 

The six linker directives are summarized below and described in detail in the 
following sections. 



Directive 



Description 



# alias 
#define 

# include 

tmainentry 
#reference 
fsection 



Defines a set of aliases for a symbol name. 

Assigns an integer value to a symbol name. Not applicable to 

occam programs. 

Specifies a linker indirect file. 

Defines the program main entry point. 

Creates a reference to a given name. 

Defines the linking priority of a module, 



Note: Symbol names are case sensitive. 



9.4.1 falias basename {aliases} 

The #alias directive defines a list of aliases for a given base name. Any reference 
to the alias is converted to the base name before the name is resolved or defined. 
For example, if a module contains a call to routine proca, which does not exist, 
then another routine proc_d may be given the alias proc_a in order to force the 
calt to be made to routine proc_d. 

#alias proc_d proc_a 
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In the above example the reference to proc_a is considered to be resolved. 
Modules may be loaded from the library for proc_d but the linker will not attempt 
to search for library modules for proc_a. If a procedure called proc_a is found 
in any module then an error will result as the symbol will be multiply defined. 

9.4.2 #def ine symboiname value 

The #def ine directive defines a symbol and gives it a value. This value must 
either be an optionally signed decimal integer, or an unsigned hexadecimal 
integer (If it is the latter it must be preceded by a # sign). #def ine is also 
discussed in section 9.5.4. 

Note: this directive is not applicable to Occam. 



9.4.3 #include filename 

The # include directive allows a further linker indirect file to be specified. Linker 
indirect files can be nested to any level The following is an example of nested indi- 
rect files: 

— user's .Ink file: 

userprocl . too — module 

#mainentry proc_a — main entry point directive 

#include sub. Ink — nested indirect file 

— user's sub. Ink file: 

userproc2 . tco — further modules 

userproc3 . tco 

userlib.lib — library 



9-4.4 #mainentry symboiname 

The #mainentry directive defines the main entry point of the program i.e. the top 
level function of the program. This directive is equivalent to the 'ME 1 command line 
option. Only one main entry point may be specified. If it is omitted the linker will 
select the first valid entry point in its input as a default. If there is more than one 
such symbol the linker will warn that there is an ambiguity. 

For C and FORTRAN programs the supplied linker indirect startup files define the 
system main entry point. 



9.4.5 #reference symboiname 

The freference directive creates a forward reference to a given symbol. This 
adows names to be made known to the linker in advance, or forces linking of library 
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modules that would otherwise be ignored. The purpose is to allow the inclusion of 
library initialization routines which might not otherwise be included. For example: 

#ref erence open 

The above example causes open to be included in the link, whether it is needed 
or not. 



9.4.6 tsection name 

The #section enables the user to define the order in which particular modules 
occur in the executable code. 

In order to use this directive the program modules must have been compiled using 
the compiler pragma lMS_linkage (C programs) or LINKAGE (Occam 
programs). Details of the appropriate directive can be found within the compiler 
reference chapter of this manual. 

A compiler directive enables a section name to be associated with the code of a 
compilation module. A section name may take the default value 
"pri%text%base* or a name specified by the user. 

The linker will place modules associated with the section name 
u pri%text%base" first in the code of the linked unit, in the order in which these 
modules are encountered. When the linker directive tsection is used this default 
condition is overridden. The modules identified by user defined section names will 
be placed first in the Linked module, in the order in which the fsection directives 
are encountered. These will be followed by any other modules in an undefined 
order at the end of the linked unit. 

For example: 

#section firflt%section%name 
fsection second%section%name 

In the above example any modules identified by first%section%name will be 
linked first, followed by modules identified by second%section%name, followed 
by any other modules. 



9.5 Linker options 



9.5.1 Processor types 

A number of options are provided to enable the userto specify the target processor 
for the linked object file, see appendix B, Only one target processor or transputer 
class may be specified and this must be compatible with the processor types or 
transputer class used to compile the modules. 
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If no target processor is specified, the processor type for the linked object file will 
default to a T414 processor type. 

If any input file in the list is incompatible with the processor type in use, the lin k fails 
and an error is reported. 

9.5.2 Error modes - options H, S and X 

Linked code may be generated in three error modes. For C or FORTRAN modules, 
compiled respectively using ice or if 77, the error mode will be UNIVERSAL, 
Occam modules, compiled by oc, may be compiled in one of three error modes 
as shown in table 9.2. 



Error mode Description 



HALT 
STOP 
UNIVERSAL 



An error halts the transputer immediately. 

An error stops the process and causes graceful degradation. 

Modules compiled in this mode may be run in either HALT or 
STOP mode depending on which mode is selected at link time. 



Table 9.2 Error modes 

Modules that are to be linked together must be compiled for compatible error 
modes. C and FORTRAN modules can be mixed with Occam modules and 
occam modules compiled for different error modes may also be mixed. Table 9.3 
indicates the compilation error modes which are compatible and the possible error 
modes they may be linked in. 



Compatible error modes 


ilink options 


HALT, UNIVERSAL 
STOP, UNIVERSAL 


H 
S 



Table 9.3 ilink error modes 

Note: Modules which have been compiled in UNIVERSAL error mode may be 
linked in this mode using the X option. If the resulting linked unit is then processed 
by the icollect tool it will be treated as if it had been linked in HALT mode. 

The linker will produce an error if an input file is in a mode incompatible with the 
command line options or defaults. The linker default is to create linked modules 
in HALT mode unless otherwise specified. 

9.5.3 TCOFF and LFF output files - options T, LB, LC 

These three options enable the format of the linked unit output file to be changed. 
The linker will default to TCOFF output if none is specified. 
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Option T specifies that the linked unit is to be output in TCOFF format. This file may 
then be processed normally by other tools in the toolset, for example, the confi- 
gurer and collector tools. 

The lb and LC options specify that the linked unit is to be output in LFF format so 
that it is compatible with previous toolsets. The LB option produces a file compat- 
ible with the iboot and iconf tools used by earlier INMOS toolsets. (See footnote 
2). The specified main entry point of the linked program is then available for boot- 
strapping by iboot or configuring by iconf. The LC option is used only in mixed 
language systems incorporating occam programs. No main entry point need be 
specified. 

When the LB and LC options are used the linked output file will not be compatible 
with the current toolset, which requires TCOFF format. 

9.5.4 Extraction of library modules - option EX 

The EX option instructs the linker to extract the modules which would normally 
have been linked by the ilink command, and to insert them unmodified into an 
output file. When the ex option is used, the linker does not produce a linked unit 
as output Instead it outputs a concatenation of the component modules that would 
have made up the linked unit This file can then itself be used as input to either the 
linker or librarian. By default the output file produced will have the extension . lku, 
although it is not a linked unit. An alternative output filename and extension can 
be specified using the ilink option. 

This mechanism can be used for creating sub units for linking at a later date or for 
extraction of modules from libraries. 

When linking or extracting modules the linker attempts to resolve any unresolved 
references. The linker u option and the #reference directive are particularly 
useful for controlling the extraction of unlinked modules. For non-occarn modules 
the #def ine directive can also be used to refine the selection of modules which 
are extracted. Linker options and directives used in conjunction with the EX option 
do not modify the extracted modules, they just influence the selection process. 

Example: Extraction from a user library 

This example demonstrates how to extract sub-parts of a previously supplied 
library. 

Suppose we are given a library, mylib. lib, which contains routines with entry- 
points start, run, clear, and stop. These routines may also call other modules 
which reside in the same library, but we are not concerned about their exact 
names. We can use the linker's EX option to extract a sub-library, which just 
contains start, run, and stop, but does not contain clear. 

We do this by forcing the linker to find' references to start, run and stop, but 
leave out clear. 
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1 Create the following linker indirect file x . Ink: 

— Items wanted 
# reference start 
# reference atop 
# reference run 

— Libraries 
my lib. lib 

2 Use ilink to extract the required modules and place them in a named file; 

ilink -f x.lnk -o sublib.tco -ex (UNIX) 

ilink It x.lnk /o sublib.tco /ex (MS-DOS and VMS) 

This command will create a file called sublib . tco which will contain all the 
submodules required. 

3 The librarian can then be used to create a library: 

ilibr sublib.tco -o sublib. lib (UNIX) 

ilibr sublib.tco /o sublib. lib (MS-DOS and VMS) 

Example: Extraction from a user library, using the run-time library 

The example demonstrates how to extract sub-parts of a previously supplied 
library which uses the run-time library. 

Consider the same example as that described above, but where the routines 
start, stop and run have calls to the run-time library embedded inside them. 
We have to tell the linker not to complain about these references, because they 
will be resolved later, when sublib , lib is used. 

1 We do the same as before, butwetellthelinkernoUocomplainaboutunre- 
solved references, by using the u command line flag: 

ilink -f x.lnk -o sublib.tco -ex -u (UNIX) 

ilink /f x.lnk /o sublib.tco /ex /u (MS-DOS and VMS) 

2 sublib . tco then be supplied to the librarian in the same way as before. 

Example: Extraction from a user library, for multiple processor types 

Suppose we are supplied with mylib. lib which contains the routines start, 
stop, run, and clear for both T400 and TA, and that we wish to create a library 
sublib. lib which contains everything except clear. 

1 We use the same method as the first example to extract the T400 code: 

ilink -£ x.lnk -o sublib. t* -ex -U00 (UNIX) 

ilink /f x.lnk /o sublib. t4 /ex /t400 (MS-DOS and VMS) 

This command will create a file called sublib . t4 which will contain alt the submo- 
dules compiled for T400. 
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2 We do the same again for TA: 

ilink -f x.lnk -o aublib.ta -« -t* (UNIX) 

ilink ft x.lnk /o sublib.ta /« /ta (MS-DOS and VMS) 

This command will create a file called sub l lb . ta which will contain all the su bmo- 
dules compiled for TA. 

3 The librarian can then be used to create a library containing both: 

ilibr sublib.ti sublib.ta -o aublib.lib (UNIX) 

ilibr subiib.t4 sublib.ta /o aublib.lib (MS-DOS and VMS) 

Example: Generation of a completely linkable library 

Suppose we have built a library mylib. lib, which requires access to the run- 
time library, and we wish to supply this to another person, without having to supply 
the run-time library separately. We can arrange for the linker to extract all the 
required parts of the run-time library and add them to mylib. lib. 

1 Create a linker indirect file x. Ink which contains #ref erence lines for 
each symbol in mylib. lib: 

— Items wanted 
# reference start 
Ireferenca atop 
f reference run 

— Libraries 
mylib . lib 

— Linker indirect file to access run-tune library 
linclude occama ■ Ink 

The run-time library line should be adjusted depending on the type of 
processor which is being used: 



Language 


When 


Linker indirect filet 


C 


Full runtime library 


olibs . Ink 


C 


Reduced run-time library 


clibsrd . Ink 


occam 


32-bit processors without an FPU 


occama . Ink 


occam 


32-bit processors with an FPU 


occamS . Ink 


occam 


16-bit processors 


occam2 . Ink 


t The C linker indirect files apply to the Dx314 toolsets and the occam 
indirect files to the Dx305 toolsets. 



2 Use ilink to extract the required modules and place them in a named file: 

ilinfc -f x.lnk -o fulllib.tco -ex (UNIX) 

ilinfc /f x.lnk /o fulllib.tco /ex (MS-DOS and VMS) 
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This command will create a file called f ulllib . tco which will contain all 
the submodules required. 

3 The librarian can then be used to create the extended library full- 
lib, lib which will contain the user library together with any routines 
which are required from the run-time library 

ilxbr f ulllib. tco -o f ulllib, lib (UNIX) 

ilibr f ulllib. tco /o f ulllib. lib (MS-DOS and VMS) 

Extraction using #def ine 

A module is the smallest unit the linker can extract from a library, and a module may 
contain several functions. It is quite likely that a module contains functions which 
are not required as well as functions which are referenced from modules which are 
required. To prevent a function from being extracted it is assigned a dummy value 
within a #def ine directive; any value will do. This causes any reference to it to 
be satisfied. 

When the linker encounters a reference to a required function it will extract the 
whole module. However, if the module contains a function already specified in a 
#def ine directive, the function will be multiply defined and the linker will abort the 
extraction. It may be wise when a function is not required, to define all functions 
which are exported from that module, to some dummy value, thereby preventing 
them all from being extracted. 

9.5.5 Display information - option I 

This option enables the display of linkage information as the link operation 
proceeds. 

9.5.6 Virtual memory - option KB 

The KB option allows the user to specify how much memory the linker will use for 
storing the image of the users program. By default the linker will attempt to store 
the entire image in memory. In situations where memory is limited, an amount ( ^ 1 
Kbytes) may be specified. If the program is larger than the amount specified then 
the linker will use the host filing system as an intermediate store. A reduction in 
speed may be expected at link time. 

9.5.7 Main entry point - option ME 

The ME option defines the main entry point of the program i.e. the point from which 
linking will start. This option is equivalent to the #mainentry directive and takes 
as its argument a symbol name which is case sensitive. 

Only one main entry point may be specified. If it is omitted the linker will select the 
first valid entry point in its input as a default. If there is more than one such symbol 
the linker will warn that there is an ambiguity. 
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9.5.8 Link map filename - option MO 

This option causes a link map file to be produced with the specified name. A file 
extension should be specified as there is no default available. By convention the 
first character of the extension should be 'd'; the 2nd and 3rd characters are deter- 
mined by the extension of the linker object file. For example, if the linker object file 
takes the default extension .Iku, the map file should be given the extension .dku. 

If the MO option is not specified, a separate link map file is not produced. 

A link map file is a text file containing information about the position of modules in 
the code file, see section 9.7. It is intended to be used as input to the imap tool, 
see chapter 12. 

9.5.9 Linked unit output file - 

The name of the linked unit output file can be specified using the o option. If the 
option is not specified the output file is named after the first input file given on the 
command line and a . lku extension is added. If the first file on the command line 
is an indirect file the output file takes the name of the first file listed in the indirect 
file. 

Note: Because there is no restriction on the order in which files may be listed it is 
up to the user to ensure that the output file is named appropriately. 

9.5.1 Permit unresolved references - option u 

The linker normally attempts to resolve all external references in the list of Input 
files and reports any that are unresolved as errors. 

Sometimes it is desirable to allow unresolved external references, for example 
during program development. The u option allows the link to proceed to completion 
by assuming unresolved references are to be resolved as zero. Warning 
messages may still be generated and the program will only execute correctly if 
such references are in fact redundant. 

9.5.11 Disable interactive debugging - Y 

This option applies only to the Occam modules only. The option directs the linker 
not to use library calls for channel i/o but instead use transputer instructions, 
resulting in faster execution. Occam modules cannot be interactively debugged 
if this option is used. 

9.6 Selective linking of library modules 

Library modules that are compiled for incompatible processor types or error 
modes are ignored by the linker. This allows library modules to be selectively 
loaded for specific processor types or transputer classes. 
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Libraries supplied with the toolset are supplied in several forms to cover the 
complete range of transputer types. User libraries that are likely to be used on 
different transputer types should be supplied for all transputer types likely to be 
used. 

Libraries are also selected for linking on the basis of previous usage. Modules that 
are used by several input files are linked in only once. 



9.7 The link map file 

Module data and details of the target processor are always included in the linked 
unit output file in the form of a comment. This information may also be directed to 
a named output file by using the HO command line option. 

The file contains a map of the code being linked and contains information which 
may assist the user during program debugging. It is intended as input to the imap 
tool, see chapter 12. 

The map file is generated in text format and covers two categories of input file; 
separate compilation units, and library modules. The map consists of single line 
records containing a number of fields. Fields have a single character name 
followed by a colon. The following information is included: 



9.7.1 MODULE record: 

A module record is created for each component module in the linked unit. 



Record 
name 


Description 


N 


Module number assigned by the linker. 


S 


Source filename, may be empty if string is unobtainable. 


F 


Object filename, the name of the file of library from which the 
module has been loaded. This will be the full path name. 





File offset, the offset (in bytes) of the module within its object file. 


R 


Reference, an external symbol that is used for loading the module 
from a library. This field will be blank it the module was not loaded 
from a library. 


M 


The compilation mode, processor type/class. 



9.7.2 SECT record: 

A section record is created for each section in the linked unit and shows where it 
is located. 
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9.8 Using imakef for versfon control 



Record 
name 


Description 


N 


Section number assigned by the linker. 


R 


Name of the section. 


A 


Section attributes, where R - read, W - write, X - execute, D - 
debug, V - virtual. 


P 


Whether the code has been placed at a fixed address; either N (no) 
or Y (yes). 


O 


The offset in bytes of the section within the code. 


S 


The size in bytes of the section. 



9.7.3 MAP record: 

This record shows how a region of the linked unit is mapped to a module and 
section. 



Record 
name 


Description 


M 


Module number of the module that supplied this region. 


R 


Section number of the section in which this region lies. 


A 


Address of the region, in bytes. 


S 


Size of the region, in bytes. 


9.7.4 Value record: 

This record shows the value of a symbol after linkage. 


Record 
name 


Description 


N 


Name of the symbol. 





Name of the origin symbol - occam modules only. (Used by the 
linker to ensure the order of compilation is correct in respect to 
#USE) . 


M 


Module number of the exporting module. 


U 


Whether the symbol has been used (externally at least); either N 
(no) or Y (yes). 


V 


Value of the symbol after linking. Expressed as a decimal integer or 
as a section number plus byte offset into that section. 



9.8 Using imakef for version control 

The imakef tool may be used to simplify the linking of complex programs, particu- 
larly those which use libraries that are nested within other libraries or compilation 

units. 
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Note: For imakef to function correctly the special file extension system described 
in section 11 .3 and appendix A must be used. 

9.9 Error messages 

This section lists each error and warning message that can be generated by the 
linker. Messages are in the standard toolset format which is explained in 
appendix A. 

9.9.1 Warnings 

filename - bad format: reason 

The named file does not conform to a recognized INMOS file format or has 
been corrupted. 

Size bytes too large for 1 6 bit target 

The code part of the linked unit has exceeded the address space of the 
T212 derived processor family. 

filename - symbol, implementation of channel arrays has changed 

Only generated in programs where Occam code is used that was compiled 
in LFF format. The implementation of channel arrays in Occam differs 
between the earlier Occam 2 compiler and the current TCOFF-based 
configurer, and channel arrays cannot therefore be used as parameters to 
configured procedures. 

filename - symbol symbol not found 

The specified symbol was not found in any of the supplied modules or 
libraries. 

filel - usage of symbol out of step with file2 

May be generated when linking programs incorporating Occam modules 
with a #use directive, which causes the compiler to scan the file for details 
concerning certain program resources. This file must be unchanged at link 
time, and the message indicates that this is not the case. There are several 
possible causes: 

1 file? has been recompiled after fi\e1 t in which case fflel requires 
recompiling. 

2 The file that occurred in the #USE directive has been replaced by 
a different version of the file at link time. 

3 The file that occurred in the #USE directive has not been supplied 
to the linker, but the linker has located a different version of a 
required entry point elsewhere. 
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The occam compiler oc may need to scan certain libraries, of which the 
user is unaware. Specifying one of the special Occam linker indirect files 
occam2 ,lnk, occama . Ink or occam8 .Ink should take care of these 
'hidden' libraries. 

9,9.2 Errors 

filename - name clash with symbol from filename 

May be generated when linking mixed language programs incorporating 
occam modules. 

In languages such as Occam entry points may be scoped, i.e. extra 
information is associated with each symbol to indicate which version of that 
entry point it is. This allows programs to be safely linked even though there 
are several different versions of the same entry point occurring at different 
lexical levels within the program. 

This error indicates that a language without occam-type scoping has been 
mixed with a scoped language and a name conflict has occurred between 
a scoped and non scoped symbol. 

filename - symbol symbol multiply defined 

The symbol, introduced in the specified file, has been introduced 
previously, causing a conflict. The same module may have been supplied 
to the linker more than once or there may be two or more modules with the 
same entry point or data item defined. 

filename - symbol symbol not found 

The specified symbol was not found in any of the supplied modules or 
libraries. 

filename - usage of symbol out of step with namefile 

May be generated when linking programs incorporating modules with a 
#use directive which causes the compiler to scan the file for details 
concerning certain program resources. This file must be unchanged at link 
time, and the message indicates that this Is not the case. There are several 
possible causes: 

1 file2 has been recompiled after filel , in which case We1 requires 
recompiling. 

2 The file that occurred in the #USE directive has been replaced by 
a different version of the file at link time. 

3 The file that occurred in the #use directive has not been supplied 
to the linker, but the linker has located a different version of a 
required entry point elsewhere. 
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The Occam compiler oc may need to scan certain libraries, of which the 
user is unaware. Specifying one of the special Occam linker indirect files 
occam2 . Ink, occama.lnk or occamB.Ink should take care of these 
'hidden' libraries. 

9.9.3 Serious errors 

filename - bad format: reason 

The named file does not conform to a recognized INMOS file format or has 
been corrupted. 

filename - line number' bad format: excessively long line in indirect file 

A line is too long. The length is implementation dependent, but on all 
currently supported hosts it is long enough so as only to be exceeded in 
error, 

filename - line number- bad format: file name missing after directive 

A directive (such as include) has no file name as an argument. 

filename - line number- bad format: directive invalid number 

A numeric parameter supplied to a directive does not correspond to the 
appropriate format. 

filename - bad format: multiple main entry points encountered 

A symbol may be defined to be the main entry point of a program by a 
compiler. Only one such symbol must exist within a single link. 

filename - linenumber - bad format: non ASCII character in indirect file 

The indirect file contains some non printable text. A common mistake is to 
specify a library or module with the 'f' command line argument or an 
include directive. 

filename - bad format: not linkable file or library 

The linker expects that all files names presented without a preceding 
switch (on the command line) or directive (in an indirect file) are either 
libraries or modules. 

filename - line number- bad format: only single parameter for directive 

The directive has been given too many parameters. 
Cannot create output without main entry point 

No main entry point has been specified. 

Command line: 1k minimum for paged memory option 

When using the KB option, the amount of memory used to hold the image 
of the program being linked is specified. There Is a minimum size of 1k. 
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Command line: token 

An illegal token has been encountered on the command line. 
Command line: bad format number 

A numerical parameter of the wrong format has been found. 
Command line: image limit multiply specified 

The command line option 'KB' has been specified more than once. 
Command line: 'load and terminate' option set, some arguments invalid 

Options to load and terminate the linker have been specified in conjunction 
with other command line options. The linker cannot execute these options 
if it has been instructed to terminate first. 

Command line: multiple debug modes 

The command line option Y has been specified more than once. 
Command line: multiple error modes 

More than one error mode has been specified to the linker. 
Command line: multiple module files specified 

The command line option 'MO' has been specified more than once. 
Command line: multiple output files specified 

The command line option '0' has been specified more than once. 
Command line: multiple target type 

More than one target processor type has been specified to the linker. 
Command line: only one output format allowed 

The options 'T\ 'LB 1 and 'LC' are mutually exclusive. 
filename - could not open for input 

The named file could not be found/opened for reading. 
filename - could not open for output 

The named file could not be opened for writing. 
filename - line number- could not open for reading 

The file name specified in an include directive could not opened. 
Could not open temporary file 

The 'KB' option has been used in a directory where there is no write access 
or not enough disc space. 
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filename - mode: mode - linker mode: mode 

The linker has been given a module to link which has been compiled with 
attributes incompatible with the options (or lack thereof) on the linker 
command line. 

Invalid or missing descriptor for main entry point symbol 

Applies to occam modules only. The specified main entry point to the 
program does not have a valid Occam descriptor. This occurs if the wrong 
symbol name has been used r for example a data symbol in C. 

Multiple main entry points specified 

The main entry point has been specified on the command line or in an indi- 
rect file more than once. 

Filename - line number- directive not enough arguments 

The wrong number of arguments have been supplied to a directive, 

filename - nothing of importance in file 

The file name specified in an include directive was empty or contained 
nothing but white space or comments. 

Nothing to link 

Various options have been given to the linker but no modules or libraries. 

filename - fine number- only one file name per line 

More than one file name has been placed on a single line within an indirect 
file. 

filename - fine number- directive too many arguments 

The wrong number of arguments have been supplied to a directive. 

Unknown error modes not supported in the LFF format 
Unknown processors not supported in the LFF format 

When generating LFF format files, certain constructs will have no repre- 
sentation. For example processor types that have come into existence 
since the LFF format was defined. 

filename - line number- unrecognised directive directive 

An unrecognized directive has been found in a linker indirect file. 

9.9.4 Embedded messages 

Tools that create modules to be linked with ilink may embed "messages" within 
them. Three levels of severity exist; serious, warning, and message. The docu- 
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mentation of the appropriate tool should be consulted for more information. The 
format of these messages is as follows: 

Serious - 11 ink - Filename - message: message 
Warning - ilink - Filename - message: message 
Message - ilink - filename - message 
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This chapter describes the binary lister tool ilist, which takes an object file and 
displays information about the object code in a readable form. The chapter 
provides examples of display options and ends with a list of error messages which 
may be generated by ilist, 

10.1 Introduction 

The binary lister tool ilist reads an object code file, decodes it, and displays 
useful information about the object code on the screen. The output may be redi- 
rected to a file. Command line options control the type of data displayed. 

The ilisttool can decode and display object files produced by ice, by the linker, 
librarian, configurer and collector tools, and by other compatible INMOS compilers 
such as the occam 2 compiler oc. Files in editable ASCII format are listed without 
further processing. 

The ilist tool will also list compilation and linked units in Linker File Format used 
by earlier versions of the INMOS toolsets (such toolsets are the IMS 
D705/D605/D505 and the D711/D611/D511 series toolsets). 

Also, because ilist uses the same method to locate files as the other tools (see 
section A.4) it can be used to find and display the location of header files and library 
files in the search path specified by I search. 

10.2 Data displays 

There are several categories of data that can be displayed. Categories are 
selected by options on the command line. The main categories are: 

• Symbol data - symbol names in each module. Information is displayed in 
tabular form. 

• External reference data - names of external symbols used by each 
module. Information is displayed in tabular form. 

• Module data - data for each module including target processor, compila- 
tion mode, and module file name. 

• Code fisting - code contained in each module, displayed in hexadecimal 
format. 

• Index data - the content of library indexes. 

• Procedural data - for external occam calls only. 
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10.2.1 Modular displays 

Object code files reflect the modular structure of the original source. Single unit 
compiJations produce a file containing a single object module, whereas units 
containing many compilations, such as libraries and concatenations of modules, 
produce object files with as many object modules. The data produced by ilist 
reflects the modular composition of object files. 



10.2.2 Example displays used in this chapter 

Except where indicated, the example displays used in this chapter show the output 
generated from the lister for the compiled (. tco) file generated by ice for the 
'Hello World' example program. The program was compiled for a T425 processor. 



10.3 Running the binary lister 

To invoke the binary lister use the following command line: 

► ilist {filenames} {options} 

where; filenames is a list of one or more files to be displayed. 

options is a list of one or more of the options given in Table 10.1 . 



Options must be preceded by '-' for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upperorlowercaseandcan be given In any 
order. 

Options must be separated by spaces. 



Only one filename may be given on the command line. 

If no arguments are given on the command line a help page is displayed giving the 
command syntax. 

Note; Options will only be applied to files of the appropriate file type. If the file 
cannot be displayed by the specified option, an error message is generated and 
the file is not displayed. 

Example of use: 

ilist hello, tco -a (UNIX based toolsets) 

ilist hello. tco /a (MS-DOS and VMS based toolsets) 



72TDS367 01 March 1993 



10 ilist- binary lister 



207 



Option 


Description 


A 


Displays all the available information on the symbols used within 
the specified modules. 


C 


Displays the code in the specified fiie as hexadecimal. This 
option also invokes the T 1 option by default. 


E 


Displays all exported names in the specified modules. 


H 


Displays the specified file(s) in hexadecimal format. 


I 


Displays full progress information as the lister runs. 


M 


Displays module data. 


N 


Displays information from the library index. 


filename 


Specifies an output file. If more than one file is specified the last 
one specified is used. 


p 


Displays any procedural interfaces found in the specified 
modules. 


R reference 


Displays the library module(s) containing the specified refer- 
ence. This option is used in conjunction with other option to 
display data for a specific symbol. If more than one library file is 
specified the last one specified is used. 


T 


Displays a full listing of a file in any file format. 


W 


Causes the lister to identify a file. The filename (including the 
search path if applicable) is displayed followed by the file type. 
This is the default option. 


X 


Displays all external references made by the specified modules. 



Table 10.1 ilist command line options 

ilist will attempt to identify the file type by its contents. If filenames only are 
supplied, ilist uses the default option 'w" and simply displays the file's identity. 

Examples of ilist usage and the displays generated by the options can be found 
in succeeding sections. 



10.3,1 Options to use for specific file types 

Table 1 0.2 lists the available options and indicates which file formats they may be 
used to list. The table also lists the file types it is recommended to use with each 
option, in order of usefulness. 
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10.4 Specifying an output file - option 



Option 


Permitted file format 


Recommended usage 


H 


Any format 







Any format 




T 


Any format 




W 


Any format 




A 


TCOFF only 


.lib, . too, .lieu 


C 


TCOFF only 


.too, .lku, .lib 


E 


TCOFF only 


.lib, .tco, .lku 


M 


TCOFF only 


.tco, .lku, .lib 


N 


TCOFF libraries only 


.lib 


P 


TCOFF only 


.lib, .tco, .lku 


R 


TCOFF libraries only 


.lib 


X 


TCOFF only 


.lib, .tco, .lku 



Table 10.2 Recommended options 
10.3.2 Output device 

ilist sends its output to the host standard output stream, normally the terminal 
screen. Facilities available on the host system may allow you to redirect the output 
to a file, or send it to another process, such as a sort program. For details of these 
facilities consult the documentation for your system. Alternatively the ilist 'Q' 
command line option may be used to redirect output to a specified file. 



10.3.3 Default command line 

A set of default command line options can be defined for the tool using the ilis- 
TARG environment variable. Options must be specified using the syntax required 
by the command line. 

10.4 Specifying an output file - option o 

The O option enables the user to redirect the display data to an output file. If more 
than one output file is specified on the command line then the last one specified 
Is used. File extensions should be specified, because defaults are not assumed. 

Display options are described in the following sections 10.5 to 10.15. Options are 
given in alphabetical order. 
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10.5 Symbol data - option a 

This option displays all the available information about the symbols used within the 
specified modules. A tabular format is used. 

Note: The data produced by this display is extensive and detailed and assume 
some knowledge of the object file format 

The following information is given: 

• Symbol name. 

• Section attributes, if applicable, 

• Symbol attributes. 

• The number of the symbol within the module plus the number of its origin. 

• Module name. 

• Target processor. 

• Error mode. 

• Interactive debugging - if disabled indicated by the presence of a¥ char- 
acter If this field is blank then interactive debugging is enabled. 

10.5.1 Specific section attributes 

Certain attributes apply only to symbols which are section names. If they are appli- 
cable, these attributes are indicated by the following nomenclature and displayed 
as a character string: 



R 


-Read section. 


W 


-Write section. 


X 


- Execute section. 


D 


- Debug section. 


V 


- Virtual section. 



10.5.2 General symbol attributes 

Attributes for all symbols, including section names, are also indicated by a char- 
acter string, using the following nomenclature: 
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10.6 Code listing - option C 



Symbol 


Description attribute 


L 


Symbol local to the module. 


E 


Symbol exported from the module. 


I 


Symbol imported to the module. 


W 


Weak attribute, indicates that the symbol takes the value when 
not defined. 


C 


Conditional attribute, indicates that the first value given to the 
symbol is always used. 


u 


Unindexed, indicates that the symbol is not present in the library 
index. 


p 


Provisional attribute, indicates that the last value given to the 
symbol is always used. 





Indicates that the symbol is an origin symbol. The origin symbol 
is used by the linker to check the origin of the module. 



Symbol attributes are displayed immediately after the section attributes, and each 
attribute is displayed at a specific position in the string. Attributes which are not 
present are indicated by a hyphen '-'. 

The position of each attribute in the string is as follows: 
RWXDV LEIWCUPO 



10,5.3 Example symbol data display 

Figure 10.1 shows the symbol data display for the compiled file hello . too. 



module%table%base 


V -E 


hello. c 


T425 X 


module%number 


L 1 


hello. c 


T425 X 


static%base 


V -E 2 


hello. c 


T425 X 


local%static 


1 3 


hello. c 


T425 X 


%lsb 


1 4 


hello. c 


T425 X 


text%ba.se 


R-X E- 5 


hello. c 


T425 X 


local%text 


.- L g 


hello, c 


T425 X 


next% common 


E— CU-- 7 


hello. c 


T425 X 


main 


E ___ — a 


hello. c 


T425 X 


_IM5_printf 


1 9 


hello. c 


T425 X 


static%space 


E UP- 10 


hello. c 


T425 X 



Figure 10.1 Example output produced by the A option. 



10.6 Code listing - option c 

The 'C option produces a full listing of the code in the same format as that gener- 
ated by the 'T' option, but with the addition of a hex listing of the code at each 
load_text directive. This option may be accompanied by the 't' option; if the 'T' 
option is not specified it is supplied automatically. 
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The output from this option gives an ASCII dump, in hexadecimal format, of the 
code for each module. It can be used on any object code. 

When used to display object code produced by the occam compiler, the code for 
each module is displayed as a contiguous block of lines, where each line has the 
format: 

address ASCII hex ASCII characters 

where: address is the address of the first byte on the line, expressed as an offset 
from the start of the module. 

ASCII hex is the hex representation of the code 

ASCII characters are the ASCI I characters corresponding to the hex code. 

In all cases code is read from left to right. If a value is not printable it is replaced 
by a dot'/. 

10.6.1 Example code listing display 

Figure 1 0.2 shows the code listing display for the compiled file hello . tco. 

00000000 LINKABLE 

OQ0O0002 START_MODULE CORE FMUL FPSOP DUP WSUBDB HOVE2D CRC BITOPS FPTSTERR 

LDDEVID DBGSUP TMRDIS LDMSTVL POP BIT32 M£=23 ICALL X lang: ANSI_C " 
00000010 VERSION tool: ice origin: hello. c 
0000001E SECTION VIR EXP w module%table%base" id: 
00000034 SET_LOAD_POINT id: 
00000037 SYMBOL LOG "module %rnimber* id: 1 
00000048 DEFINELABEL id: 1 
0000004B SECTION vir EXP w 3tatic%base" id: 2 
0000005B SETJLOADPOINT id: 2 
0000005E SYMBOL LOG "local%static" id: 3 
0000006E DEFINE_LABEL id: 3 
00000071 SYMBOL LOG w %l3b* id: A 
00000079 DEFINE_SYMBOL Id: 4 SS:0+SV;3 
00000081 SECTION REA EXE EXP "text%base" id: 5 
0000008F SET_LOAD_POINT id: 5 
00000092 SYMBOL LOC "local % text" id: 6 
O0OOD0AO DEFINE_LABE1 id: 6 

O0OO00A3 SYMBOL EXP CON UNI w next%comrooi]'' id: 1 
O0OO00B2 DEFINESYMBOL id: 7 SS:2 
O0OO00B7 COMMENT bytes: 5 
O00O00C1 LOAD_EXPR size: 4 SV:1 
O0OO00C6 SYMBOL EXP "main" id: 8 
O0OO00CE DEFINE_SYMBOL id: 8 SV:6+4 
O0OO00D6 SYMBOL IMP "_IMS_printf " id: 9 
0000D0E5 LOAD_TEXT bytes: 24 

O0OOO0E8 4521FB71 219222F0 0A48656C 6C6F2Q57 El.ql .*. -Hello W 
O0OO00F8 6F726C64 0A002020 orld. . 

00000100 LOAD_PREFIX size: 6 AP(SV:9-LP) instr: j 
00000109 LOAD_TEXT bytes: 2 
0000010C 2020 

0000010E COMMENT bytes: 33 

00000134 SYMBOL EXP UNI PRO "staticSspace" id: 10 
00000144 DEFINE_SYMBOL id: 10 SV:7 
00000149 END_MODULE 

Figure 10,2 Example output produced by the C option 
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107 Exported names - option e 

The output from this option is in a tabular format It consists of a list of names 
exported by the modules. This option also dispiays any globally visible data. 

The following information is given by the display: 

• Exported name. 

• The name of the module in which the exported name is found. 

• Language used. 

• Target processor. 

• Error mode. 

• Interactive debugging - if disabled indicated by the presence of a T char- 
acter. If this field is blank then interactive debugging is enabled. 

10.7.1 Example exported names display 

Figure 1 0,3 shows the exported names display for the compiled file hello . too. 

r \ 

main -> hello. c ANSI_C T425 X 



Figure 10.3 Example output produced by the E option 

10.8 Hexadecimal/ASCII dump - option h 

This option provides a display of the specified files in hexadecimal and ASCII 
format. The option does not attem pt to identify file types and may be used to display 
any files which the lister has previously identified incorrectly. 

The output takes the form of a hexadecimal representation of the whole of the file 
content. The display has a similar appearance to that produced by the C option, 
however, the c option only functions on code found within the file. 

Each module is displayed as a contiguous block of lines, where each line has the 
format: 

address ASCII hex ASCII characters 

where: address is the address of the first byte on the line, expressed as an offset 
from the start of the module. 
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ASCII hex is the hex representation of the code 

ASCII characters are the ASCII characters corresponding to the hex code. 

In all cases code is read from left to n'ght. If a value is not printable it is replaced 
by a dot 1 /. 

10,8.1 Example hex dump display 

Figure 10,4 shows the hex dump display for the compiled file hello . tco. 



00000000 


0100020C 


FDFFFElF 


00FD52E0 


07000400 


R.... . 


00000010 


1B0C0369 


63630768 


656C6C6F 


2E630B14 


. . .ice. hello. c . . 


00000020 


1002116D 


6F64756C 


65257461 


626C6525 


. . ,module%table% 


00000030 


62617365 


0401001E 


CFO10D6D 


6F64756C 




00000040 


65256E75 


6D626572 


OE01010B 


0E10020B 




00000050 


73746174 


69632562 


61736504 


01021ECE 


static%base 


00000060 


01QC6C6F 


63616C25 


73746174 


69630E01 


, .local%static. . 


00000070 


031E0601 


04256C73 


620F0604 


06040003 


%lsb 


00000030 


030B0C06 


02097465 


78742562 


61736504 




00000090 


01051E0C 


010A6C6F 


63616C25 


74657874 




ooooooao 


0E01061B 


0D32OE6E 


65737425 


636F6D6D 


2 . next%comm 


OO00OOBO 


6F6EOF03 


07040214 


08000005 


0D008194 




ooooooco 


06080304 
08060306 


03011E06 
01041E0D 


02046D61 
040B5F49 


696E0FOG 
4D535F70 




OO00OOD0 


IMS_p 


OO00OOEO 


72696E74 


66061918 


4521FB71 


219222FO 


rintf . . .E* .ql .". 


0OQ000FC 


0A43656C 


6C6F2057 


6F726C64 


OA002020 


.Hello World. . 


00000100 


0707060D 


07030902 


00060302 


20201424 


5 


00000110 


00002103 


03010001 


0E050404 


03060800 


i 


00000120 


00QE09G8 


040EQB0A 


040EODOC 


QA040EQ4 




00000130 


0F0C101C 


1E0E620C 


73746174 


€9632573 




00000140 


70616365 


OF030AG3 


070300 







Figure 10.4 Example output produced by the B option 

1 0.9 Module data - option m 

This option displays any header information which is present. This may include 
version control data, general comments that may have been appended to the file 
during use of the toolset and copyright information. The data is displayed for indi- 
vidual modules in the object file and includes: 

• Module name 

• Transputer type and compilation error mode 

• Language type 

• Version control data 

• Comments inserted by the toolset, for example, copyright clauses. 

Data is displayed in separate blocks for each module. Some of the data is also used 
by other tools in the toolset, for example, some comments are used by the 
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debuggertool idebug while version information is used by some tools for compati- 
bility testing. 

When finked units are displayed using this option, a long comment will be 
displayed. This comment gives details of the allocation of memory to each sepa- 
rately compiled code and library module used in the linked module. The following 
information is given in tabular format: 

• Code type - Separately compiled code (SC) or library module (LIB). 

• Module name. 

• Address offset in linked module. 

• Start address. 

• End address. 

• Reference in library {if applicable) used to locate the relevant library 
module. 

10.9.1 Example module data display 

Figure 10.5 shows the module data display for the compiled file hello, tco. 



MODULE: RHSI_C T425 X 
VERSION: ice hello. c 



Figure 10.5 Example output produced by the M option 

10.10 Library index data - option n 

This option is used to list library indexes. The data is given in a tabular format. For 
each entry in the index the following information is given: 

* The address of the module in the library. 

• The symbol name. 

• The language the module is written in. 

* The target processor type. 

• The error mode used. 

* Interactive debugging - if disabled indicated by the presence of a T char- 
acter. If this field is blank then interactive debugging is enabled. 
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OCCAM 


Tft 


X 


OCCAM 


TA 


X 


OCCAM 


TA 


X 


OCCAM 


TA 


K 


ANSI C 


TA 


X 


ANSI C 


ra 


X 


ANSI C 


TA 


X 


ANSI C 


TA 


X 
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10.10.1 Example library index display 

Figure 10.6 shows part of the output produced by the IF option for one of the stan- 
dard C library files. 



00C25C21 ie64op.pax:B340AC"Jl 

00036155 xlinlcl.pax:FllEAD5A 

00034AF7 DATAN2%C 

000330DO DCOS%c 

00OOB898 DefaultSignalHandler%c 

0001CAC6 floorf 

0002007E get_static_size%c 

000129AD sub_vfprintf%c 



Figure 10.6 Example output produced by the n option 

10.11 Procedural interface data - option p 

This option is only applicable to Occam modules or mixed language programs. It 
displays procedural interface information for all external Occam functions and 
procedures. The following information is displayed for each module: 

• Target processor. 

• Error mode. 

• Language used. 

• Amount of workspace used by the procedure or function, in words. 

• Amount of vector space used by the procedure or function, in words. 

• Parameters used by the procedure or function. 

• Data type of parameters. 

• Channel usage, if applicable. 

Channel usage is displayed in Occam notation. A channel marked with an ? is an 
input channel to the code of that entry point, and a channel marked with I is an 
output channel. 

When a library file is listed this will be indicated by the words 'index ENTRY 
mode;' rather than 'DESCRIPTOR mode'. 

10.11.1 Example procedural data display 

Figure 10.7 shows an example procedural data display for a compiled Occam 
module. This example Is taken from the 'simple 1 example Occam program 
compiled by oc for the TA processor class. 
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r 




*\ 


DESCRIPTOR mode: TA B language; OCCAM 


<ORIGIN DESCRIPTOR 




DESCRIPTOR mode: TA H language: OCCAM 






ws: 52 vs: 378 






PROC 3lmple(CHAN OF SP f s, CHAN OF SP tsl 






SEQ 






fs? 






tsl 






V 




) 



Figure 10.7 Example output produced by the P option 



10.12 Specify reference - option r 

This option is used in conjunction with any of the other display options to locate a 
specific symbol within a named library. All library modules that export the symbol 
are displayed. 

The exact format of the display depends on the main display option with which r 
is used. 

Note: Symbol names must be specified in the correct case. 



10.13 Full listing - option t 

This option displays all data found in the input file. Provided that ilist recognizes 
the file type, the file is decoded in its own format. Text file are displayed as text and 
unrecognized file types are displayed as a hexadecimal dump. 

Data is not displayed in a tabular form but is output in the sequence in which it is 
found in the module. 

The display formats are tailored to each file format and are intended for diagnostic 
support and analysis; large amounts of data are produced which may require 
skilled Interpretation. 

10.13.1 Example full data display 

Figure 1 0.8 shows the full data display for the compiled file hello . tco. 
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00000000 LINKABLE 

00000002 START_MODULE CORE FMOL FPSOP DDP ffSDBDB MOVE2D CRC BITOPS FPTSTERR 

LDDEVID DBGSOP TMRDI3 LDHSTVL POP B3T32 MS-28 ICALL X lang: AKSI_C "" 
00000010 VERSION tool: ice origin: hello. c 
OOGOOQiE SECTION VIR EXP "module%table%faase' r id: 
00000034 SET_LOAD_POINT id: 
00000037 SYMBOL LOC w nodule%number" id: I 
0000048 DEFINE^LAEEL id: 1 

0000004B SECTION VIR EXP "statictbase" id: 2 

0000005B SET_LOAD_POlNT id: 2 

00OO005E SYMBOL LOC 'local%sUtic w id: 3 

00OO00SE DEFINE_LAB£L id: 3 

00000071 SYMBOL LOC "%lsb" id: 4 

00000079 DEFlNE_SYMBOL id: 4 SS:0+SV:3 

00000081 SECTION REA EXE EXP "textibase" Id: 5 

0000008F SET_LOAD_POINT id: 5 

00000092 SYMBOL LOC "local%text /r id: 6 

000000A0 DEFINE_LABEL id: 6 

OO00OOA3 SYMBOL EXP CON UNI "nextfccommoiT id: 7 

OO00OOB2 DEFINE SYMBOL id: 7 SS:2 

0O00OOB7 COMMENT bytes: 5 

OO00OOC1 LOAD_EXPR size: 4 SV:1 

0000OOC6 SYMBOL EXP "main" id: 8 

000000CE DEFINE_SYMBOL id: 8 SV:6+4 

00OO0OD6 SYMBOL IMP "_IMS_printf - id: 9 

000000E5 LOADJTEXT bytes: 24 

00000100 LOAD_PREFIX size: G AP(SV:9-LP) instr: j 

00000109 LOAD_TEXT bytes: 2 

000 00 IDE COMMENT bytes: 33 

00000134 SYMBOL EXP UNI PRO "static%space" id: 10 

00000144 DEFINE_SYMBOL id: 10 SV:7 

00000149 END MODOLE 



Figure 10.8 Example output produced by the T option 



10.13.2 Configuration data files 

The full data listing of a configured (.cfb) file shows how the processes are 
mapped onto a transputer system and has a different appearance to other displays 
produced by this option. 



10.14 File identification - option w 

This option causes the lister to identify the file type, ilist takes a heuristic 
approach to file identification. The filename is displayed along with the file type. 
The full path to the file is also displayed if the file is not in the current directory (i.e. 
if it has been found in the search path specified in the isearch environment vari- 
able). This is the default command line invocation if no other option is supplied. 

Table 10.3 indicates how the lister classifies file types, 
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10.14 File identification - option w 




File format 


Default 
extension 


Listed file type 


TCOFF compiled unit 


.tco 


TCOFF LINKABLE UNIT 


TCOFF compiled library 

unit 


.lib 


TCOFF LINKABLE UNIT LIBRARY 


TCOFF linked unit 


.lku 


TCOFF LINKED UNIT 


TCOFF linked library unit 


.lib 


TCOFF LINKED UNIT LIBRARY 


Configuration binary 


.cfb 


CONFIGURATION BINARY 


Core dump 


. dmp 


CORE DUMP FILE 


Network dump 


. dmp 


NETWORK DUMP 


LFF file 


.cxx r 
.txx 


LFFSC 


LFF library 


.lib 


LFF LIBRARY 


Extracted SC 


.rxx 


EXTRACTED SC 


iboot program 


.bxx 


BOOTABLE PROGRAM (iboot) 


Extracted program 


,btl 


BOOTABLE PROGRAM 


Empty file 


- 


EMPTY FILE 


Text files 


- 


TEXT FILE 


None of the above 


- 


UNKNOWN BINARY FORMAT 



Table 10.3 File types recognised by ilist 

where: SC files are separately compiled files. 

LFF files are separately compiled or linked files in LFF format 

Extracted files are files which have been compiled and developed to be 
dynamically loaded onto a transputer system. 

iboot programs are programs which have had a bootstrap added by the 
iboot tool, supported by previous issues of the toolset i.e. the IMS 
D711/D611/D511 and D705/D605/D505 series toolsets. 

10.14.1 Example file identification display 

Figure 10.9 shows the file identification display for the compiled file hello . tco. 
and two linker control files. This output was generated by the following command: 

ilist hello. tco occama.lnk clibsrd.lnk 
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hello. too TCOFF LINKABLE UNIT 

/home/D4205/libs/occama.lnk TEXT FILE 

/home/D4300/libs/clibsrd.lnk TEXT FILE 



Figure 10.9 Example output produced by the w option 

10.15 External reference data - option x 

This option displays a list of all the code and data symbols imported by the modules 
specified to the lister, i.e. it lists their external references. External references are 
references to separately compiled units. For C programs the option will also display 
any external references to globally visible data. 

The output from this option is in a tabularformat It consists of a list of external refer- 
ences and their associated modules. The following information is displayed: 

• External reference i.e. name of the separately compiled unit. 

• The name of the module in which the external reference exists. 

• Language used. 

• Target processor. 

• Error mode. 

• Interactive debugging- if disabled indicated by the presence of a 'Y' char- 
acter. If this field is blank then interactive debugging is enabled. 

10.15.1 Example external reference data display 

Figure 10.10 shows the external reference data display for the compiled file 

hello, tco. 



_lMS_j>rintf <- hello. c ANSI_C T425 x 



Figure 10.10 Example output produced by the X option 

10.16 Error messages 

This section lists error and warning messages that can be generated by the lister. 
Messages are in the standard toolset format which is explained in appendix A. 
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10.16.1 Warning messages 

filename - reason 

The named file does not conform to a recognized INMOS file format 
or has been corrupted. 

10.16.2 Serious errors 

filename - bad format: reason 

The named file does not conform to a recognized INMOS file format 
or has been corrupted. 

filename - could not open for input 

The named file could not be found/opened for reading. 
filename - could not open for output 

The named file could not be opened for writing. 

filename - file type does not correspond to command line options 

The options given to the lister apply to formats dissimilar to the 
format of the file being read. 

must supply additional TCOFF options with reference reference 
The required format of the listing has not been specified. 

filename - no entry for reference in library index 

The specified reference cannot be found in the library index. 

parsing command Line token 

An unrecognized token was found on the command line. 

filename - unexpected end of file 

The named file does not conform to a known INMOS file format or 
has been corrupted. 
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1 1 imakef — makefile 
generator 



This chapter describes the makefile generator imakef that creates makefiles for 
input to make programs. It explains how the tool can be used to create makefiles 
and describes the special file naming conventions that allow imakef to create 
makefiles for mixtures of code types. The chapter describes the format of makefiles 
generated by imakef and ends with a list of error messages. 

11.1 Introduction 

Make programs automate program building by recompiling only those components 
that have been changed since the fast compilation. To do this they read a makefile 
which contains information about the interdependencies of files with one another, 
along with command lines for rebuilding the program. 

imakef creates makefiles for all types of toolset object files, using its built in knowl- 
edge of how files referenced within the target file depend on one another. It is 
intended to be used with all I NMOS compiler systems that generate TCOFF object 
code, which includes the the ANSI C compiler ice, the Occam 2 compiler oc and 
the FORTRAN-77 compiler if 77. Its mode of operation with different languages 
is controlled by command line options. The makefile is generated in a standard 
format for input to most make programs. 

Makefiles created using imakef are compatible with many public domain and 
proprietary make programs. The following make programs are directly compatible: 

• Borland make. 

• UNIX make. 

• Microsoft nmake. 

• Gnu make. 

However, the older Microsoft make program "make" is not compatible. 

The source of imakef is supplied with the toolset so that it can be modified for use 
with other make programs. 

11.2 How imakef works 

imakef operates by working back from the target file to determine its depen- 
dences on other files, using its knowledge of inputs and outputs of each tool and 
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the compilation architecture of the toolset. For example, compiled object files must 
be created from language source files using the compiler 

In a similar way linked files must be generated from compiled files, imakef 
assumes that programs targeted at a single transputer are not required to be confi- 
gured. Bootable files may therefore be generated from linked units or configuration 
data files, imakef works back from the target file, determining file dependencies 
and creating commands to recreate the target file, recompiling and relinking where 
necessary. 



11.3 File extensions for use with imakef 

imakef Identifies files a nd file types by a special set of file extensions which iden- 
tify the transputer target type and compilation error mode. This allows the tool to 
produce makefiles for mixed module combinations. 

Note: The extensions that imakef requires differ In most cases from the standard 
toolset default extensions which are described in section A.5. For imakef to work 
correctly the extensions described in section 11.3.1 must be used on all inter- 
mediate and target files, at all stages of program development i.e. compiling, 
linking, configuring, and booting. 

The file naming convention uses a three-character extension which identifies the 
type of file and in most cases includes the transputer target and error mode. Source 
files for the most part use standard language extensions. 

11.3.1 Target files 

The following table lists the types of object code files for which imakef can create 
makefiles, along with the file extension formats that must be used. 



Target file 


File extension 


Compiled code. 


.txx 


Linked code. 


r cxx 


Bootable code for single transputer programs. 


.hxx 


Bootable code for muititransputer programs. 


.btl 


Dynamically loadable code. 


.zxx 


Libraries. 


.lib 


Configuration binary file. 


.cfb 


Library usage file. 


.liu 


Library indirect file. 


.lbb 



Compiled, linked, bootable and non-bootable files, whatever their language origin, 
have a transputer target designator as the second character of the extension, and 
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an error mode designator as the third character. Accepted values of these designa- 
tors are listed below. 



2nd 
Character 


Transputer types 

supported 


2 


T212,T222, M212 


3 


T225 


4 


T414 


5 


T426, T425, T400 


8 


T800 


9 


T805, T801 


a 


Class TA 


b 


Class TB 



3rd 
Character 


Error mode 


X 


UNIVERSAL 


h 


HALT 


s 


STOP 



Examples: 

.t4x - refers to a compiled module targetted for T4 transputers, in 
UNIVERSAL error mode. 

. tah - refers to a module targetted for any 32-bit transputer in HALT error 
mode. 

Compiled code generated by ice or if 77 is in UNIVERSAL mode, designated by 
the character 'x\ HALT and STOP code can be generated by the Occam 2 
compiler oc. 

Transputer types are explained further in section B.2. 

Program development using imakef and the extensions to use are illustrated in 
Figure 11.1. Target files which can be created by imakef are shown in bold. 
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11,3 File extensions for use with intake f 




Figure 11.1 Main target files showing extensions required 
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1 1 .4 Linker indirect files 

For C and FORTRAN modules linker indirect files must be created for all linked 
units where imakef will be used to generate a target file. Linker indirect files define 
to imakef the components of the linked unit, providing a starting point for working 
out file dependencies. 

Linker indirect files must be named after the linked unit to which they relate and 
cany the . Ink extension. 

For programs written wholly in Occam, imakef will automatically generate a 
linker indirect file. The file is named after the target filename but is given an exten- 
sion in the form . lxx. The file contains a list of modules to be linked. In addition 
an #include statement references a further tinker indirect file, referencing 
compiler libraries, imakef deduces the compiler libraries to be included from the 
extension of the linked object file. 

Section 1 1 .6.2 provides a short description of linker indirect files and several exam- 
ples are given in section 11.7. 



11.5 Library indirect and library usage files 

When building a library using imakef, a file must be provided that contains the 
names of all the object modules required to build the library. This file is known as 
a library indirect file and has the extension .lbb. See chapter 8 for further details. 

Library usage files describe the dependencies of a library on other libraries or 
separately compiled code. They contain a list of files to which the library must be 
linked before it can be run, and ensure that the correct linker commands are gener- 
ated. 

Library usage files should be created for all user-defined libraries where the source 
of the library is not available. They are created using imakef. 

Library usage files are given the same name as the library to which they relate, but 
with a . liu extension. To create a library usage file using imakef, specify the 
library name and add a .liu extension. For example, the following command 
creates a library usage file for the library mylib. lib: 

imakef mylib . liu 
When imakef is used to create a library usage file no makefile is generated. 



11.6 Running the makefile generator 

The imakef tool takes as input a list of files generated by tools in the toolset and 
generates a makefile, containing full instructions of how to build the application 
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11.6 Running the makefile generator 



program. The output file is named after the first target filename and is given a .male 
extension (If no output file is specified on the command line). 

To invoke imakef use the following command line: 
► imakef filenames {options} 



where: filenames is a list of target files for which makefiles are to be generated. If 
more than one file is specified the single makefile generated will generate 
all of the specified files. 

options is a list, in any order, of one or more options from Table 11.1. 



Options must be preceded by '-' for UNIX-based toolsets and V for 
MS-DOS and VMS based toolsets. 

Options may be given in any order. 

Options may be entered in upper or lowercase and can be given in any 
order 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Option 


Description 


c 


This option is used when incorporating C or FORTRAN modules 
into the program. It specifies that the list of files to be linked is to be 
read from a linker indirect file. This option must be specified for 
correct C or FORTRAN operation. 


D 


Disables the generation of debugging information in compilations. 
The default is to compile with full debugging information. 


I 


Displays full progress information as the tool runs. 


M 


Produce compiler, linker and collector map files for imap. 


NI 


Files in the directories in ISEARCH are not put into the makefile. 
This means that system files are not present, making it much easier 
to read. 


filename 


Specifies an output file. If no file is specified the output file is named 
after the target file and given the .mak extension. 


R 


Writes a deletion rule into the makefile. 


Y 


Disables interactive (breakpoint) debugging in all compilations. 
The default is to compile with full breakpoint debugging information. 



Table 111 imakef options 
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11.6.1 Example of use 

imakef hello. b4x -c (UNIX based toolsets) 

imakef hello. b4x /c (MS-DOS and VMS based toolsets) 

This creates the makefile hello. mak which when used as input to make gener- 
ates the bootable file hello. b4x (a bootable file for T4 transputers). 

11.6.2 Specifying language mode 

imakef can be used with all compilers in the INMOS TCOFF family. This includes 
the ANSI C compiler ice, the Occam compiler oc as well as the FORTRAN 

compiler if 77. 

imakef has two modes of operation: one for the traditional languages FORTRAN 
and C, and another for occam. occam mode is the default; FORTRAN and C 
operation is controlled by a command line option. 

In occam programs, file dependencies are wholly deducible from the source and 
target files. In FORTRAN and C programs the list of files to be processed by the 
linker must be created in a linker indirect file; use of the imakef 'C option instructs 
imakef that there are linker indirect file(s) to be read. The linker indirect files must 
include all the components of a program, including any libraries that are used. 

The 4 C* option must be specified for all C and FORTRAN programs and for any 
mixed language programs which incorporate modules in these languages. For 
mixed language programs all files which are to be linked must be listed in the linker 
indirect file(s), including any Occam modules or library files. In systems that use 
mixtures of code compiled for different transputer types and error modes, a sepa- 
rate linker indirect file must be created for each. 

An example is given in section 11 .7.3 of how imakef may be used to build a mixed 
language program. 

11.6.3 Configuration description files 

When imakef builds a makefile for a configured program it will look for the pres- 
ence of a configuration description file which has the same name as the program 
to be built. 

The type of file searched for depends on the mode of operation specified to 
imakef. If the default occam mode is used, that is, the 'c' option is not specified, 
imakef will look first for a configuration description file with the extension . pgm, 
(readable by the Occam configurer ccconf). Ifa , pgm file is not present imakef 
will then look for a . cf s file (readable by the 'C-style' configurer icconf ). 

If the FORTRAN/C mode is used, that is, the 'C option is specified, the reverse 
sequence is used, that is, imakef looks first for a . cf s file. 
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11.6.4 Disabling debug data 

Two options to imakef disable the creation of debug data. 

The 'D' option disables the generation of alt debugging information in the target file. 
If this option is used the resulting target code cannot be debugged. 

The 'Y 1 option disables only the data required for interactive (breakpoint controlled) 
debugging. If this option is given no breakpoint debugging operations can be used 
on the final program. Post-mortem debugging is unaffected. 

11.6.5 Removing intermediate files 

Intermediate files can be removed by specifying the 'R' option to imakef. This 
adds a delete rule to the makefile which directs make to remove all intermediate 
after the program is built. The delete operation Is only honored if make is subse- 
quently invoked with the DELETE option. 

11.6.6 Files found on ISEARCH 

When imakef runs, it includes all dependencies in the set of rules. The HI option 
prevents imakef recording in the makefile, any dependencies on files found using 
ISEARCH. As a result the makefile is easier to read and is more portable. 

11.6.7 Map file output for imap 

Using the W option, imakef can be made to generate switches in the calls to the 
compiler, linker or collector to output map files. These map files are then available 
for reading by the imap tool, details of which can be found in chapter 12. 



1 1 .7 imakef examples 

This section contains several examples of the use of imakef with different 
programming languages. The final example shows how a mixed language 
program can be built with imakef. 

The sources appropriate to the toolset are supplied in the examples subdirectory. 
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11.7.1 C examples 

The first example shows how to create a makefile for a multi-module program, 
written in C, running on a single transputer. The second example shows how to 
create a makefile for a configured C program. 

Single transputer program 

This first example is for a program which is not configured. 

The example program is made up of three source files, written in C: 

main.c 

hellof .c 

worldf . c 

imakef needs to know the names of the main components of the program, and 
looks for the associated linker indirect file hello . ink: 

hello . Ink must contain the following text: 

main. t4x 
hellof. t4x 

worldf . t4x 

#include cnonconf , Ink 

Note: the use of the . t4x extension rather than . tco. This is because imakef 
needs to work out the required processor type. The startup linker indirect file 
cnonconf .Ink is also included. The inclusion of this file is standard for all C 
programs which are not configured and directs imakef to include the libraries. To 
create the makefile use the command: 

imakef hello, b4x -c (UNIX based toolsets) 

imakef hello .b4x /c (MS-DOS and VMS based toolsets) 

Note: the use of the . b4x extension instead of . btl. Using this form of extension 
informs imakef that we wish to create a bootable program for a single transputer 
without the aid of the configurer. The makefile hello. mak is created. 
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Multitransputer program 

This example program uses the configurer to place linked units on two processors. 
The program is made up of the following source files written in C: 

master . c 
mult . c 
multi . cf s 

The .cfs file is the configuration description file. It places 2 linked units on 2 
processors, using the following statements: 

use "master.cSx" for master ; 
use "mult.c4x" for mult; 

Note : the use of the . cxx form of extension instead of the toolset default exten- 
sion for linked units . Iku. imakef reads the . cfs file and determines that the 
program is made up of two linked units, each of which must have an associated 
linker indirect file, namely, master . Ink, and mult . Ink. 

The two linker indirect files files must contain the following text: 

master.lnk: multi nk: 

master . t8x mult. t4x 

#include cstartup.lnk finclude cstartrd.lnk 

Again note the use of the . txxform of extension, master . Ink includes the linker 
indirect file cs tar tup . Ink, which is used for configured programs linked with the 
full runtime library, mult .Ink includes cstartrd. Ink, the standard linker Indi- 
rect file used for configured programs linked with the reduced library. This library 
can be used by mult . t4x because the module does not require host access. 

To create the makefile use the following command: 

imakef multi. btl -c (UNIX based toolsets) 

imakef multi .btl /c (MS-DOS and VMS based toolsets) 

The .btl extension informs imakef that the target is a configured program, to be 
built from a configuration description file called multi, cfs. The makefile 
multi .mak is created. 

Note: when multi, mak invokes the configurer, the following warning is issued: 
Warning-icconf-Using single hop software virtual links 

This warning may be ignored. 
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11.7.2 occam examples 

Two examples are again provided, the first for a multi-module program running on 
a single transputer and the second example for a configured program. 

Single transputer program 

The example program is made up of four source files, written in occam: 

sorthdr . inc 

element. occ 

inout . occ 

sorter. occ 

The sources are the same as those used in the sorter example described in the 
Toolset User Guide. 

To create the makefile use the following command: 

imakef sorter. b4h 

Note the use of the .b4h extension instead of .btl. Using this form of extension 
informs imakef that we wish to create a bootable program for a single transputer 
without the aid of the configurer. 

The makefile generator has built-in knowledge of the file name rules for Occam. 
In this example, it knows by examining the file name that the program to be built 
is for a single T414 processor in HALT mode, and that the source of the main body 
of the program is in the file sorter. occ. It reads the file sorter* occ and 
discovers that it uses a library called hostio.lib, the two compilation units 
inout and element, and two include files, sorthdr . inc and hostio . inc. It 
then reads the sources of the include files and compilation units and finds no more 
file dependencies. 

With this information about source file and their dependencies, imakef builds a 
makefile called sorter. mak containing full instructions on how to build the 
program and creates a linker indirect file sorter . 14h (see section 11 .4). 

To build the program run the make program on sorter .mak. The entire program 
will be automatically compiled, linked and made bootable, ready for loading onto 
the transputer 
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Multitransputer program 

Th is version of the sorter program is configured to place linked units on four proces- 
sors. It is based on the configured sorter program described in the Toolset User 
Guide and uses the same sources. 

The program is made up of the following occam files: 

sorthdr . inc 
element . occ 
inout . occ 
sortconf. pgm 
To create the makefile use the following command: 

imakef sortconf .btl 

The . btl extension informs imakef that the target is a configured program, to be 
built from a configuration description file called sortconf , pgm. The configuration 
description references two linked units: 

#USE "inout. c4h" 
#USE "element. c4h" 

Note: the use of the . cxx form of extension instead of the toolset default extension 
for linked units . iku. imakef reads the .pgm file and will produce a file called 
sortconf ,mak containing a make description of the program. 

To build the program run the make program on sortconf .mak. 



72 TDS 367 01 March 1993 



11 imakef - makefile generator 233 



11.7.3 Mixed language program 

This example, uses a mixed language program which combines both Occam and 
C modules. It is based on the example given in the 'Mixed language programming' 
chapter of the accompanying User Guide. 

The example program is made up of the following files: 

mixed. t4h - Compiled Occam module 

cfunc- t4x - Compiled C module 

where: the Occam module is the main program which calls in the C function. 

To create the makefile for the example program use one of the following 
commands: 

imakef mixed. b4h -c (UNIX based toolsets) 

imakef mixed. b4h /c (MS-DOS and VMS based toolsets) 

This command informs imakef that we wish to create a bootable program for a 
single T414 processor in HALT mode. The 'c' option tells imakef that the program 
also includes modules written in C. 

imakef needs to know the names of the C components of the program, and looks 
for the associated linker indirect fife mixed. Ink. Because a linker indirect file is 
supplied to imakef, all the modules to be linked must be listed. 

mixed. Ink must contain the following files: 

mixed. t4h 

cfunc.t4x 

callc.lib 

hostio . lib 

#INCLODE clibsrd.lnk 

#INCLUDE occama.lnk 

The occam module is listed first, because it contains the main entry point of the 
program. Note: the use of the . t4h and . t4x extensions. The C module has been 
compiled in UNIVERSAL mode, which is the standard mode for the C compiler. 
This does not cause a problem because UNIVERSAL mode may be called by 
HALT mode. 

The files hostio . lib and callc . lib are the Occam libraries, occama . Ink 
contains a list of Occam compiler libraries which may be required. 

clibsrd. Ink references the reduced C runtime library used by the C module. 

With this Information imakef builds the make program mixed, raak. 
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Further information about mixed language programming can be found the accom- 
panying User Guide. 

11.8 Format of makefiles 

Makefiles essentially consist of a number of rules for building all the parts of a 
program. Each rule contains two main elements: a definition of the file's dependen- 
cies in a format acceptable to make programs; and the command to recreate the 
file on a specific host. All makefiles also contain macros which define command 
strings and option combinations. 

11.8.1 Macros 

All makefiles created by imakef include a set of macro definitions inserted at the 
head of the file. 

Macros define strings which are used to call the compiler, the configurer, the linker, 
the librarian, the collector, and the eprom formatter tools, and fixed combinations 
of options for these tools. 

Macros are provided so that customized versions of the toolset commands, and 
specific combinations of options, can be easily incorporated. Existing macros can 
be modified for specific host environments, and new macros created, by editing the 
makefile. 

The full set of macros defined by imakef can be found by consulting any makefile 
created by the tool. 

11.8.2 Rules 

Rules define the dependencies of object files on other files and specify action 
strings to build those files. 

Example: 

UNIX based toolsets: 

example . t4h : example , c 

$(CC) example -t4 -b -o example. t4h $ (COPT) 

MS-DOS and VMS based toolsets: 

example . t4h : example . c 

$(CC) example /t4 /h /o example. t4h $(COPT) 

This rule first defines the target as the compiled program example . t4h, which is 
dependent on the source file example .c and then specifies the command that 
must be invoked to build it. 
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The first rule in all makefiles is for the main target. Succeeding rules define sub- 
components of the main target, and are listed hierarchically. 

Action strings 

Action strings define the complete command line needed to recreate a specific file. 
The format is similar for all tools and consists of a call to the tool via a predefined 
macro, a fixed set of parameters, a list of command line options, probably also via 
a macro, and the output filename. (The output file Is specified on the command line 
so that the rebuilt file is always written to the directory that contains the source.) 

11.8.3 Delete rule 

The delete rule directs make to remove all intermediate object files once the 
program has been built. It consists of a single labelled action string which invokes 
the host system 'delete file 1 command. Deletion is only performed if make is subse- 
quently invoked with the DELETE option. 

The delete rule is appended to the makefile by specifying the imakef *R' option. 

11.8.4 Editing the makefile 

Makefiles created by the imakef tool can be edited for specific requirements. For 
example, new macros can be added and new rules defined for compiling and 
linking code written in other languages. 

Adding options 

imakef generates action strings which have the minimum of options for each tool. 
In most cases additional options are unnecessary or may be specified using 
compiler directives. To modify the set of default options for a particular tool simply 
edit the appropriate macro in the makefile. 

For example, if the output of progress information is to be enabled for all invoca- 
tions of the compiler, the compiler T option would be added to the macro which 
defines the standard combination of options for invoking the compiler. Alternatively 
a new macro containing only the T option could be defined and added to each 
compiler action string. 

Re-running imakef 

Once the set of options have been changed in the macros, it is useful to retain this 
set of options when imakef is run again. For this reason, imakef will check for 
the existence of a previous makefile, if one exists, it will re-use (in the new make- 
file) the set of macro definitions from the old one, plus any additional text up to a 
line marked "imakef cut*. 

11.9 Error messages 

imakef generates error messages of severities Warning and Error Messages are 
displayed in standard toolset format 



72TDS367 01 March 1993 



236 11.9 Error messages 



Cannot have a makefile 

The file specified on the command line is not one for which imakef can 
generate a makefile, iaakef can only create makefiles for object files and 
bootable files. 

Cannot open "filename" -.reason 

The file specified as the output file cannot be opened for writing by the 
program, for the reason given. 

Cannot write linker command file 

The linker command file cannot be opened for writing by the program. 

Command line is invalid 

An incorrect command line was supplied to the program. Check the syntax 
of the command and try again. 

Error whilst reading 

A file system error has occurred whilst reading the source. 

#IMPORT references are illegal in configuration text 

At the given line number in the file there is a reference to the #IMP0RT 
directive, which is illegal for configuration source, 

#INCLUDE may not reference a library 

The fINCLODE directive is being used to reference a file with the . lib 
extension. 

#INCLUDE may not reference binary files 

The #ihclude directive is being used to reference a file containing 
compiled code. 

Incomplete compiler directive 

At the given line number in the file there is an invalid compiler directive. 

Library on PATH "pathname 19 also exists in the current directory 

A library with the specified name has been found on the current search path 
and in the current directory. 

Malloc failed 

The program has failed while trying to dynamically allocate memory for its 
own use. Try using a transputer board with more memory. If the program 
is being run on the host it may be possible to increase the memory available 
using host commands. 

Options are incorrectly delimited 

The terminating bracket, which determines the options in a library build file, 
is missing at the given line number 
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#SC references are illegal in configuration text 

Applies to occam modules only. 

At the given line number in the file there is a #SC directive, which is illegal 

in configuration source code. 

#SC, #USE may not reference source files 

Applies to Occam modules only. 

The directives #sc and #use cannot be used to reference Occam source 

code. 

Source file does not exist 

The referenced source file does not exist on the system. 
Target is not a derivable file 

The specified file cannot be generated by the toolset. 
Tree checking failed ■ no output performed 

The tree of files has been found to be invalid and unusable for generating 
makefile. This message always follows a message indicating what is wrong 
with the tree. The most common reason for this error is the presence of 
cyclic references in the source. 

"filename" unknown/illegal file reference 

A compiler directive is attempting to reference the wrong type of file. 
Writing file 

A host system error occurred while the file was being written. 
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This chapter describes the memory map tool imap. The tool takes the text output 
from the toolset compiler linker and collector and gives the absolute addresses 
of the static variables and functions. The chapter begins with an introduction to 
imap and explains the command line syntax, imap's output is described in some 
detail and an example is given. The chapter ends with a list of error messages. 

12.1 Introduction 

The imap tool takes as input memory map files output by the compiler, linker and 
collector. Command line options for these tools enable the user to specify that a 
memory map file is to be produced . imap collates the information from the different 
source files and puts it in a format suitable for output on the display screen. Alterna- 
tively the output from imap can be redirected to another output file as the user 
wishes. Memory maps may be generated for both single and multiprocessor trans- 
puter programs. 

imap is invoked by supplying it with the name of a map file produced by the 
collector. The tool will automatically determine the names of map files produced 
by the linker and compiler, provided the naming convention for extensions has 
been adhered to, see section 12.2.1. Each tool generates a different level of 
information: 

Collector: For each process on each processor, memory locations of code, 
static, heap, stack, invocation stack and vector space are listed. 

Linker: For each process the offset in memory for code and static for 
individual modules which make up the process are listed. 

Compiler: For each module listed in the linker output file the offset in 

memory for individual static items, procedures and functions are 
listed. 

Where a particular category of information is not applicable to a language, this field 
will be left blank. Occam prog ramsfor instance do not use heap, so obviously such 
details are not generated for Occam. 

Where the output files from the compiler and linker cannot be opened or parsed 
properly imap will insert a warning at the appropriate point in the output. 

The operation of the map tool in terms of standard toolset file extensions Is shown 
below. Output is sent to standard out, which is usually set to the display screen. 
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12.2 Running the map too] 



miap 



Input 
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Ldxxj LwxxJ 



r f^=fr 






12.2 Running the map tool 

To invoke the map tool use the following command line: 

► imap filename {options} 

where: filename is the name of the file containing the map outputfrom the collector 
icollect. If there is no extension given, . map is assumed. Otherwise the 
file name is taken as given. 

options is a list of the options given in Table 12.1 



Options must be preceded by '-' for UNIX-based toofsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be entered in upper or lower case and can be given in any 
order. 

Options must be separated by spaces. 



Only one filename may be given on the command line. 

If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Examples of use: 

imap myprog 

imap myprog. map 

Both the above examples will cause imap to read the file myprog . map, generated 
by the collector. 
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Option 


Description 


A 


Displays the list of symbols produced by the linker, including 
those symbols the linker identifies as not being used. This 
option will not override the 'R' option if it is used. 


I 


Displays progress information as imap processes informa- 
tion from the input files, such as the filenames of files as they 
are opened and closed. 


o filename 


Specifies an output fife. 


R 


This option reduces the amount of detail generated by imap 
in two ways: 

• the Module memory usage table only displays 
details for user modules i.e. 'USER' and 
'SHAREDJJSER 1 processes. 

• the Symbol table excludes those symbols containing 
a '%' character in their name. Such symbols are 
normally internal symbols e.g. C runtime library 
symbols. 


ROM hex offset 


This option is only applicable to, and must be specified for, 
code targetted at ROM . It enables a hexadecimal offset to be 
specified which represents the start address of the code in 
ROM. This offset will be added to the start address of any 
code which is to run in ROM, in imap's output. 



Table 12,1 imap command line options 



12.2.1 Source files required by imap 

Three different types of source file are read by imap and should therefore be made 
available. The files are in fact memory maps generated by the compiler, linker and 
collector. The appropriate command line option must be specified on each tool's 
command line including a filename for the map produced. The filename specified 
by the user must have the appropriate extension as indicated in table 12.2. 



Extension 


File description 


.mxx 


Map file output by the compiler. The characters xx 1 are determined 
by the 2nd and 3rd characters of the extension given to the compiler 
object file. For example if the compiler object file takes the default 
extension . tco, the information file is given the extension .mco. 


.dxx 


Map file output by the linker. The characters xx' are determined by 
the 2nd and 3rd characters of the extension given to the linker 
object file. For example if the linker object file takes the default 
extension . lku, the information file is given the extension .dfcu. 


.map 


Map file output by the collector. 



Table 12.2 Files extensions for imap source files 
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12.2,2 Re-directing imap's output 

imap's output goes to standard out by default. To redirect it to an output file, use 
the 'o' option and specify an output filename. 



12.3 Output format 

This section describes the format of the memory map produced by imap. An 
example output is given in section 124. 

If the imap tool cannot find a linker or compiler output file, it will insert a warning 
message in place of the missing information. It will not produce a warning if the 
process or module comes from a library (such as the system process library). 
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12.3.1 imap memory map structure 

• All processors used are listed. Details for each processor are as follows: 

• Processor name - if specified by the user in a configuration data file. 

• Processor Id. - a unique number which is assigned by the collector. 
These numbers start from zero, and increase by one for each processor. 

• Processor type e.g. T400, T805 etc. 

• A list of processes, (in the same order as the collector output file). The 
following details are given for each process as appropriate: 

© Process Id, - a three digit number assigned by imap. Process 
numbers start at 000 and are incremented by 1 for each new process. 

o Process priority - HIGH or LOW 

© Process type - user; sharedjjser; initsystem; system or 
OVERLAiD_SYSTEM. See table 12.3. 

q Process name, if specified by the user. 

o List of linked units or a library from which the process is made. For 
each Jinked unit or library the following details are included: 

o Name of the linked unit or library 

o The file offset in memory, expressed as a decimal number. 

o The offset from the start of the linked unit or library, at which code 
for that process begins, (expressed as a decimal number). In a 
linked unit this will usually be a very small number, pointing to just 
after the header, whereas in a library, where the code is selected 
from a number of related chunks of code, the offset may point to 
anywhere within the library. 

o A list of modules that make up the unit. The list is in the same 
order as the linker output file. Details include: 

- Module Id. - a three digit module number assigned by imap. 

- TCOFF object filename. 

- Name of the source file from which the object was generated. 

• A table of the memory blocks allocated to user processes. See 12.3.3. 

• A table of the code and static memory blocks used by individual modules, 
including the section of memory that each block represents. See 12.3.4. 

• A table of the memory blocks that non-user processes use. See 12.3.5. 

• A table of symbols used by all of the processors. See 12.3.6. 
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12.3.2 Process types 



Process type 


Description 


INITSYSTEM 


A process used En the initialization of the transputer 
network. 


OVERLAXD_SYSTEM 


System process which is overwritten by other processes 
after it has been used. 


SYSTEM 


A process used in the initialization and running of the 
network. 


USER 


A user process. 


SHARED_USER 


A user process whose code can be used by more than 
one process. 



Table 12.3 Process types 

12,3.3 User processes 

The table headed with "User processes' 9 gives the start and end addresses and 
lengths of the various blocks of memory used by the user processes for that 
processor. The table is ordered by start address and is structured as follows: 

• Process number or 'All' if it is the parameter data block, which is not asso- 
ciated to just one process. 

• Memory block type - stack; overhd; code; heap; static or param. 
See table 12.4. 

• Start address in hexadecimal. 

• End address in hexadecimal. 

• Length in decimal. 



Block type 


Description 


stack 


Used for workspace 


overhd 


Used for invocation stack 


code 


Used for code 


heap 


Used for heap 


static 


Used for static data 


param 


Used for the parameter data block 


vector 


Used for vector space (for occam programs) 



Table 12.4 Memory block types 

12.3.4 Module memory usage 

The table headed with "Module memory usage* gives the memory areas that are 
used by each module for code or static data. The table is ordered by start address 
and has the following format: 
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• Process i.d. 

• Module i.d. 

• Type (code or static) 

• Name of the section that the area belongs to 

• Start address in hexadecimal. 

• End address in hexadecimal. 

• Length of the area in decimal. 

Examples of section names are pri%text%base and text%base for code, and 
static%base for static data. 

If the 'R' command line option is used only details of user processes are shown, 

12.3.5 Other processes 

The table headed with "Other processes" is the same as the "User processes" 
table but for all the non-user processes. This table will not include an entry for the 
parameter data block. 

12.3.6 Symbol table 

The symbol table is alphabetically ordered by symbol name and gives the following 
information: 

• Symbol name. 

• Processor Id. 

• Process Id. 

• Module Id. 

• Start address associated with symbol (in hexadecimal). 

• Symbol type (see below). 

The type field of the symbol table is eithertaken directly from the compiler map file, 
or is created by imap. In the latter case, the field will be enclosed in parentheses. 
This information is based on which section the symbol comes from. Refer to the 
compiler documentation forthe meaning of items in this field that aren't enclosed in 
parentheses. 

Note: command line options can be used to extend or limit the amount of symbol 
information generated. Normally imap only gives details of symbols used by the 
program; the 'A' option instructs imap to include unused symbols in the list. The 
'R J option prevents details of internal symbols, such as those used by the runtime 
libraries, being listed. 
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12.4 Example 

The following example, for a single processor program, was generated by the 
command: 



imap test -r 
imap test /r 



(UNIX) 
{MSJ30S and VMS) 



Memory map for 'testl' 
Map for processor (T800) 
List of processes 



?:000 - LOW priority INITSYSTEM process: 
From 'sysproc.lib' (offset 4969) 



Init. system' 



P:001 - LOW priority SYSTEM process; 'System. process. a' 
From 'sysproc.lib' [offset 13391) 

P:002 - HIGH priority SYSTEM process: ' System. process. b' 
From 'sysproc.lib' (offset 28774) 



P:003 - LOW 
From 'tes 
M:000 
M:001 
M:002 
M:0Q3 
M;004 
M:0Q5 
M:006 
M:007 
M:008 
M:0C9 
M:010 
M:011 
M:012 
M:013 
M:014 
M;015 
M:016 
M:017 
M:01S 
M:019 
M;02Q 
M:021 
M:Q22 
M:023 
M:Q24 
M:025 
M: 026 
M:027 
M:028 
M:029 
M:030 



tmp' 



from 



from 

from 
from 



priority USER process: 
ttBOO.lku' (offset 25 
Module 'testtSOO.tco' from ' testt300 .c' 

Module '/inmos/prod/d4214b/libs/centry.lib' from 'tmp.occ' 
Module ' /inmos/prod/d4214b/lib3/libc.lib' from 'exit.pSx' 
Module '/inmos/prod/d4214b/libs/libc.lib' from 'virtual. tmp 
Module '/inmos/prod/d4214b/libs/libc.lib' from 
Module '/inmos/prod/d4214b/libs/libc.lib' from 
Module ' /inmos/prod/d42l4b/libs/libc.lib f from 
Module ' /inmos/prod/d42Hb/libs/libc.iib' from 
Zinnias /prod/d42l4b/libs/libc. lib' 
/inmos/prod/d4214b/libs/libc.lib' 
Module '/inmos/prod/d4214b/libs/libc.lib' 
Module '/inmos/prod/d4214b/libs/libc.lib' 
/inmo3/prod/d4214b/libs/libc.lib' 
/inmos/prod/d4214b/libs/libc.lib' 
/inmos/prod/d42l4b/libs/libc.lib' from 
/inmos/prod/d4214b/libs/libc.lib' from 
/inmos/prod/d4214b/libs/Iibc.lib' from 
/inmos/prod/d42l4b/libs/libc.lib' from 
/inmos/prod/d4214b/libs/libc.lib' from 
/ initios /prod M421 4 b/libs/libc. lib' from 
/inmos/prod/d4214b/lib5/libc,lib' from 
/inmos/prod/d4214b/libs/libc.lib' 
Module ' /inmos/prod/d4214b/libs/libc.lib' 
Module '/inmos/prod/d4214b/libs/libc.lib' 
/inmos/prod/d^^b/libs/libclib' 
/inmos/prod/d4214b/llbs/libc.lib' 
/inmos/prod/d42l4b/libs/libc.iib' 
/inmos/prod/d4214b/libs/libc.lib r 
/inmos/prDd/d42l4b/libs/libc + lib' 
/inmos/prod/d4214b/libs/libc.lib 



Module 
Module 



Module 
Module 
Module 
Module 
Module 
Module 
Module 
Module 
Module 
Module 



Module 
Module 
Module 
Module 
Module 
Module 



Module ' /itimos/prod/d4214b/libs/libc.l±b' 



semprocs. 
support. c' 
chandeb.c' 
plus .c' 
newsem2.c' 
from 'printf.c' 
from 'stdioini.c' 
trap. s' 
crunl.c' 
crun2.c' 
ioprgnam.c' 
iocmdlin.c' 
iscndlin.c' 
isbuf . c' 
ismisc.c' 
isversn.c' 
ctype-c' 
clock. c' 
ptime.c' 
atexit,c' 
ioinit.c' 
agwalloc.c' 
f lushbuf -c' 
misc.c' 
fflush.c' 
<fabricated>' 
istaticc' 



from 

from 
from 
from 
from 
from 
from 
from 
from 
from 



Figure 12.1 imap example, screen 1 of 3 
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M:031 - Module ' /inmos/prod/cl4214bmbs^libc. 

M:032 - Module r /inmos/prod/d4214b/libs/libc, 

M:033 - Module ' /inmos/prod/d4214b/libs/libc, 

H:034 - Module ' /inmos/prod/d4214b/libs/libc. 

M:035 - Module '/inmos/prod/d4214b/libs/libc< 

Mi036 - Module ' /inmos/prod/d4214b/libs/libc. 

M:037 - Module ' /inmo5/prod/d4214b/libs/libc. 

M:038 - Module ' /inmos/prod/d4214b/libs/libc. 

M:039 - Module ' /iTunos/prod/d4214b/libs/lIbe. 

M:040 - Module ' /iiunos/prod/d4214b/libs/libc, 

M:041 - Module '/inmos/prod/d4214b/libs/libc. 

M:042 - Module ' /lnnas/prod/d4214b/libsyiibc. 

M:043 - Module ' /inmos/prod/d4214b/libs/libc. 

M:044 - Module ' /inmos/prod/d4214b/libs/libc. 

M:045 - Module ' /inmos/prod/d4214b/lib3/libc. 

M:046 - Module ' /inmos/prod/d4214b/libn/Ubc. 

M:047 - Module ' /inmo3/prod/d4214b/libs/libc. 

M:048 - Module ' /inmos/prod/d4214b/libs/libc. 

M:049 - Module ' /inmos/prod/d42l4b/libs/libc. 

M:050 - Module ' /iumos/prod/d42i4b/llbs/libc. 

M:051 - Module ' /inmos/prod/d4214b/libs/libc. 

M;0B2 - Module ' /inmos/prod/d4214b/libs/libc. 



lib' 


from 


' tmp . s ' 


lib' 


from 


' ioisatty.c' 


lib' 


from 


' trap . s ' 


lib' 


from 


'memcpy.c' 


lib' 


from 


'memmove. c' 


lib' 


from 


'memset. c' 


lib' 


from 


'fpprintf .c' 


lib' 


from 


'math.c' 


lib' 


from 


' strcpy.c' 


lib' 


from 


' strlen .c' 


lib' 


from 


'fseek.c' 


lib' 


from 


' iofsize.c' 


lib' 


from 


' isf seek-c' 


lib' 


from 


' isf tell. c' 


lib' 


from 


' clearerr.c' 


lib' 


from 


'ftell.c' 


lib' 


from 


' vfpriintf .c' 


lib' 


from 


' writebuf .c' 


lib' 


from 


' iolseek.c' 


lib' 


from 


' iowrite.c' 


lib' 


from 


' isf flush. c' 


lib' 


from 


'isfwrite .c' 



User processes: 
Process Type Start 



End 



Length 



P:003 stack #80000154 #80000267 

P:003 overhd #80000258 I8000Q27E 

P:003 code #30000284 I8C004E2F 

P:All param #8GQ04E30 #8C004FEF 

P:003 static #800C52A0 #8C0O54D9 



276 

20 

19372 

443 

570 



Module memory useage: 
Process Module Type 



Section 



Start 



End 



Length 



P:003 M;000 
P:003 M:000 
P:003 M:000 



code textfcbase 

static module%table%base 

static static^base 



#80000284 #800005C7 
#8Q0052A0 #8Q0052A3 
#80005300 #8000531B 



B36 

4 
28 



Other processes : 
Process Type 



Start 



End 



Length 



:002 

:002 

:002 

:000 

:000 

:000 

P:0G1 

P:001 

P:001 

P:001 



stack 

overhd 

code 

stack 

overhd 

code 

stack 

overhd 

code 

vector 



#80000154 
#3000016C 
#80000188 
#80004FFO 
#80005060 
#80005080 
#800052A0 
#800054B8 
#BO0054D4 
I80005E20 



fSOOOOUB 
#8000017F 
#80000lE3 
#8000505F 
#30005077 
#3000529F 
#300054B7 
#800054CB 
#80005E1F 
#8000601F 



24 
20 
92 

112 
24 

544 

536 

20 

2380 

512 



Figure 12.2 imap example, screen 2 of 3 



72 TDS 367 01 



March 1993 



24S 



12.4 Example 



Table of symbols 


Processor 


Process Module 


Start 


Type 


Symbol name 


C. ENTRY 





P:0D3 


M:001 


#8000Q5C9 


(code) 


_IMS_IsFileBuffer 





P;003 


M:005 


#80005364 


(static) 


IMS StartTime 





P:003 


M:005 


#8G00532C 


(staticj 


_IMS_SystemLink 





P:003 


M:005 


♦3000535C 


(static) 


_IMS_board_type 





P:0C3 


Mi005 


*300055A0 


(static) 


_IMS_closeptx 





P:QQ3 


M:024 


#80GG5A90 


(static) 


_IMS_ctype 





P:003 


M:020 


#80C05BB8 


(static) 


_ IMS_en t r y_te rmjnode 





P:O03 


M:005 


#80005330 


(static) 


_IM5_errno 





P:003 


M:Q05 


#8000531C 


(static) 


_lMS_fcloseptr 





P:Q03 


M:010 


#800055BO 


(static) 


IMS fdinap 





P:003 


M;024 


#80C05A8C 


(static) 


_IMS_fflushptr 





P:003 


M:01C 


#80005584 


(static) 


_IMS_heap_base 





P:003 


M:005 


#80005348 


(static) 


_lMS_heap_front 





P:CQ3 


M:G05 


J8QQ0534C 


(static) 


_IMS_host type 





P:003 


M:005 


#8Q00559C 


(static) 


IMS huge val 





P:003 


M:005 


#80005334 


(static) 


IMS iob 





F:003 


M:010 


#800055B8 


(static) 


_IM5_isbufsiie 





P:003 


M:005 


#80C0b5A4 


(static) 


_IMS_last_recorded_wptr 





P:003 


H:005 


#3000533C 


(static) 


_IMS max wptr extent 





P:003 


M:005 


#30005354 


(static) 


IMS os type 





P:0D3 


M:005 


#30005593 


(static) 


_IMS_printf 





P:GQ3 


M:Q09 


#30000DBA 


(code) 


_lMS_retval 


Q 


P:0Q3 


M:0Q5 


#30005326 


(static) 


_IMS shared area 





P:003 


M:005 


#80005340 


(static) 


_IMS stackbase 





P:Q03 


M:005 


130005350 


(static) 


_IMS_stack._limit 





P:003 


M:0Q5 


#30005344 


(static) 


_IMS_starteiiv 





P:003 


M:005 


#30005320 


(static) 


calloc 





P;003 


M:025 


#800020E1 


{code} 


clock 





P:003 


M:D21 


#8CD0lB54 


(code) 


exit 





P:003 


M:023 


*8000lBFD 


(code) 


exit.pSx:B905FF?C 





P:003 


M:002 


♦8QQ0Q234 


(code) 


fflush 





P:003 


M:023 


#80002727 


(code) 


free 





P:003 


M:025 


#800C20C0 


(code) 


frexp 





P:003 


M:03B 


#80003600 


(code) 


ldexp 





P:003 


M;038 


#80003580 


(code) 


longjmp 





P:003 


M:033 


#80002925 


(code) 


main 


(J 


P:003 


M:000 


#80000299 


code 


malloc 





P:Q03 


M:025 


#80001FB5 


(code) 


memcpy 





P:003 


M:034 


#80002940 


(code) 


memmove 





P:003 


M:D35 


#8000294C 


(code) 


memset 





P:003 


M:036 


#80002A60 


(code) 


printf 





P:003 


M:037 


#80003403 


(code) 


semprocs . tmp : 3B081EDC 


D 


P:003 


M:0D4 


#30000284 


(code) 


strcpy 





P;003 


M:Q39 


#800036D4 


(code) 


strlen 





P:003 


M:040 


#80003744 


(code) 


testl 





P:003 


M:QO0 


#80005300 


data 


test2 





P:003 


M:000 


#80005304 


data 


test3 





P:003 


M:000 


#80005308 


data 


testfunctiontSOO 





P:003 


M:00C 


#90000238 


code 


tolower 


G 


P:003 


M:020 


#300Q1A33 


(code) 


virtual . tmp: E5F0 6A7A 





P:0C3 


M:003 


#80000284 


(code) 



Figure 12,3 imap example, screen 3 of 3 
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12.5 Error messages 

This section lists each error message that can be generated by the memory map 
tool. Messages are in the standard toolset format which is explained in appendix A. 

Alt open files are dosed when an erroris found and the tool halts without producing 
a map. 



12.5.1 Serious errors 

Filename input file cannot be parsed properly 

The named file cannot be read by imap. 

Cannot open collector's output file for reading 

The collector map file specified on the command line cannot be found. 
Check that the extension used for the collector map file is in the correct 
format. See section 12.2. 

Cannot open output file for writing 

The output file cannot be opened for writing. May indicate a disk space 
problem or some other host system error 

Error parsing command line 

The command line has the wrong syntax ora non-existent option has been 
specified. 

Must specify input file 

An input file must be specified. 
Only single output filename allowed 

More than one output filename has been specified. 
Only single ROM offset value allowed 

More than one ROM offset has been specified. 

12.5.2 Fatal errors 

Filename internal data structure failure or file corrupt 

A source file used by imap has referenced something which cannot be 
found. This can occur when redundant mapfiles are read by imap in error. 
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Filename out of heap space 

There is not enough heap space to generate the memory map. 
Unexpected end of file 

A source file, read by imap has been corrupted. Regenerate compiler, 
linker and collector map files. 
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This chapter describes the host file server iserver which loads application 
programs onto transputer networks and provides runtime access to the host. 

This document describes version 1 .5 of the server. This is completely compatible 
with earlier versions but provides greater flexibility in the way transputers are 
accessed. In particular, the server can access transputer systems connected to a 
computer network (e.g. via Ethernet), 

A summary of the new features of this version appears in Section 13.9. 

13.1 Introduction 

The host file server iserver provides three functions: 

• Loading bootable programs onto transputer systems. 

• A runtime environment for application programs, giving access to host 
services (e.g. file and terminal \fo). 

• Controlled access to transputer systems; multiple users in a computer 
network can request a specific transputer system or a particular type of 
transputer. Access to each transputer system is granted to one user at a 
time for as long as required, 

13.2 Loading programs 

Before a program can be loaded into a transputer network it must be compiled and 
linked. Multi-transputer programs must also be configured for the transputer 
system they are to run on. The program is made bootable with the collector tool, 
icollect. The bootable file will generally have a *btl file extension. 

13.3 Host interface 

Generally, transputer applications communicate with the host file server using the 
standard i/o libraries for the language being used. The library calls available and 
their parameters will be documented in the relevant language manual. 

The communication with the host is based on a protocol, defined in appendix C. 
This protocol is used by the C, FORTRAN, and Occam run time libraries to 
communicate with the host. 
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1 3.4 Access to transputer networks 

Previous versions of the server required different code (and, therefore, a different 
executable) for every type of host interface. This version of the server provides 
support for all types of link interface in a single program. This means that when the 
server is run, it must be told what transputer systems are available and which type 
of interface to use for each. 

User Jinks 

Each transputer system can be thought of as being connected to the host by a user 
link. User links are given descriptive names (known as capabilities) which are used 
by the server to find a suitable transputer system. Programs may be loaded onto 
transputer systems down user links, whilstoperating system services are provided 
to the programs by communicating with the host file server via the user link. The 
names of the available user links, and the way in which the transputers are 
accessed, are defined in a connection database file. 

More detail on user links, the connection database file, and accessing transputer 
networks is provided in section 13.7. 

The session manager 

The iserver guarantees unique access to a transputer system while it is running. 
The system is released when the server terminates. Often , the same resource 
needs to be used to run several programs (or run one program several times). For 
example, after running a program, it may be necessary to use the debugger— it 
would not be very useful if another user had started using the transputer between 
the program failing and the debugger starting. 

The server's session manager allows access to a resource to be guaranteed for 
as long as required. The session manager is started with the J SM' option and 
provides a simple command line interface. AU the normal host operating system 
commands can be used as well as the iserver and session manager commands. 

More detail on using the session manager are given in section 13.6. 

1 3*5 Running the iserver 

To run the host file server use the Mowing command line: 

^ iserver {options} 

where: options is a list of one or more options from Table 13.1 . 

If iserver is invoked with no options, help Information is displayed, briefly 
explaining the command line arguments. 

Some parameters can also be provided by the environment variables which are 
described in Section 13.5.2. These can be overridden by values provided on the 
command line. 
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Option 


Description 


SA 


Analyses the root transputer and peeks 8K of its memory. 


SB filename 


Boots the program contained in the named file. 


SC filename 


Copies the named file to the root transputer link. 


SE 


Terminates the server if the transputer error flag is set or a 
control link error message is received. 


SI 


Displays progress information as the program is loaded. 


sk interval 


Specifies the number of seconds between attempts to access 
the resource. 


SL name 


Specifies the capability name. 


SM 


Invokes the session manager interface. 


sp n 


Sets the size of memory to peek on Analyse to n Kbytes. 


SR 


Resets the root transputer and its subsystem. 


3S 


Serves the link, i.e. provides host system support to programs 
communicating on the host link. 


ST 


All of the following command line is passed directly to the 
booted program as parameters. 


Options must be preceded by '-' for UNIX based toolsets. 

Options must be preceded by 7' for non-UNIX based toolsets. 

There must be at least one space between options. The case of letters in the 
parameters are not significant. 

Options may be in any order, except that no further options may appear after ST. 

Option 'SB filename' is equivalent to 'SR SS SI SC filename'. 



Table 13.1 Host file server options 



13.5.1 Examples of use 



UNIX based toolsets; 



MS-DOSA/MS based toolsets: 



ice hello 

ilink hello.tco -f cstadupJnk 

icconf helto.cfs 

icollect hello.cfb 



ice hello 

ilink hello.tco if cstartupJnk 
icconf hello.cfs 
icollect hello, cfb 



iserver -sb hello. btl -se iserver /sb hello. btl /se 

In this example iserver is executed to load and serve the bootable file 
hello, btl and to terminate on error. The example also shows the steps for 
compiling, linking, configuring and making the bootable file. 

Note: this example assumes that the environment variable TRANSPUTER has been 
set to the name of the user link to be used. 
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13.5.2 Server environment variables 

The server may obtain some parameters by inspecting environment variables. The 
following names are used: 

transputer Defines the capability (user link name) to be used by the 
server. May be overridden by the SL option. 

ICONDB Defines the name of the connection database file used by the 
server. 

ISESSION Defines the name of the session manager configuration file. 
The default is 'session. cfg\ 

13.5.3 Loading programs 

Before a program can be loaded onto a transputer network it must be compiled, 
linked and made bootable. 

Running a program using the iserver — option SB 

The name of the file containing the bootable program is specified using the 'SB' 
option. This resets the board and then copies the contents of the bootable file to 
the user link. If the file cannot be found an error is reported. When the program has 
been successfully loaded the server then provides host services to the program. 

Note: Using the 'SB' option is equivalent to using the SR, ss, SI and sc options 
together. 

Sending data down a user link — option sc 

To send data down a user link, or to load a program onto a board without resetting 
the root transputer, use the 'SC option — this simply copies the contents of the 
specified file to the user link. This should only be done if the transputer is running 
a program that can interpret the data sent down the link, or has already been reset. 
To reset the transputer subsystem use the 'SR' option. 

Running programs which do not use the server 

To terminate the server immediately after loading the program use the 'SR T and 'SC* 
options together. This combination of options resets the transputer, loads the 
program onto the board, and terminates the server — the program on the trans- 
puter will continue running. This can be used to run a program which does not need 
to use the server facilities. If the program on the transputer attempts to access the 
server then it will deadlock until the server is run with the 'SS' option. 

Note: single transputer programs built with the collector's T 1 option cannot be run 
in this way as the loader uses the server to read the value of the environment vari- 
able IBOARDSIZE, Configured programs (and programs built with the collector's 
V and 'M 1 options) will perform no communication with the host other than that 
specified in the user's program. 
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Analyzing a transputer network — option sa 

To load a board in analyze mode, for example when you wish to use the debugger 
to examine the program's execution, use the 'sa' option to dump a section of the 
transputer's memory {starting from MOSTNEG INT). The default amount of 
memory to dump is 8 Kbytes, but this can be overridden with the f SP' option. The 
data is stored in an internal buffer which can be read by the idump tool when 
programs that use the root transputer are to be debugged. 

Terminating the server 

When the program sends a terminate command to the server (or some serious 
error occurs) the server wilt terminate if the session manager is not being used. If 
an error occurred an error message will be printed. If the session manager inter- 
face is being used, then control will return to the session manager. 

13.5.4 Supplying parameters to a program 

Any parameters on the command line following the 'ST' option are passed as 
parameters to a booted program. This includes parameters that would normally be 
interpreted as iserver parameters. In addition, any text on the command line that 
is not recognized as a server parameter is also passed to a booted program. 

13.5.5 Specifying the transputer resource — option SL 

To specify the transputer resource to be used a capability name must be specified. 
The server may be given the capability on the command line using the 'SL' option. 

The capability may also be specified by the environment variable TRANSPUTER 
This variable is overridden by a capability specified by the 'SL' option. 

The SK option can be used to specify how frequently the server should retry if the 
requested resource is not available; by default it does not retry. 

13.5.6 Terminating on error— option SE 

When debugging programs it is useful to force the server to terminate when the 
subsystem's error flag is set. To do this use the 'SE' option. This option should only 
be used for programs written entirely in Occam and compiled in HALT system 
mode. If the program is not written entirely in Occam then the error flag may be 
set even though no error has occurred. 

13.5.7 Terminating the server 

To terminate the server press the host system break key The server will either then 
terminate, returning to the host operating system prompt, or return to the session 
manager interface prompt if the server was invoked with the 'SM* option. 
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13.6 Using the session manager interface 



13.5.8 Specifying the session manager configuration file 

The session manager configuration file contains iserver commands for use by 
the session manager and may be customized for personal use. 

The file is given by the environment variable isession. If isession is not set, 
then the filename 'session, cfg' is used. 

13.6 Using the session manager interface 

The session manager provides a mechanism for guaranteeing unique access to 
a transputer system for as long as is required. Once the server terminates, or the 
system is released from within the session manager, access to the same system 
is no longer guaranteed. 

13.6.1 Session manager commands 

The session manager has a simple command line interface. There are a number 
of commands for managing the session such as open to select the transputer 
resource to be used, and exit to terminate the session. A complete list of session 
manager commands is given in table 13.2. 



Command 


Description 


iserver parameters 


Run as server to load network and provide host 
services. This command has most of the same options 
as the normal iserver command (except, of course, 
'sl' and 'sm'). 


source filename 


Read commands from a file 


open capability 


Release any held system and open a session with the 
named capability. 


options parameters 


Specify command line parameters to iserver 
command. 


show 


List user-defined commands. 


help 


List internal and user-defined commands. 


exit or quit 


Release any held system and exit the session 
manager. 


user command 


A user-defined command. 


any other command 


Any other command is passed directly to the host 
operating system. 



Table 13.2 Session manager commands 

13.6.2 The options command 

The options command allows a set of standard options for the session manag- 
er's iserver command to be defined. Any parameters to the options command 
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are saved and added to any following iserver command. See the examples in 
sections 13.6,3 and 13,6.4. 

With no parameters, the options command displays the parameters which are 
currently set. To remove parameters which have previously been set with the 
options command, use an empty string as the parameter, i.e. 

options "" 

13,6.3 The iserver command 

The command iserver starts the server, from within the session manager, to load 
code onto the transputer system and provide host servicesto it. This command can 
be followed by any of the command line options described in section 13.5 (except 
'SL' and 'SM' which are ignored). This allows programs to be run repeatedly on the 
same transputer system. When the program running on the transputer terminates 
(whether due to a normal termination, an error condition, or a user interrupt) control 
is returned to the session manager, without releasing the transputer system. 

Note: the options to the session manager iserver command must be preceded 
by the appropriate option character as defined in tabEe 13.1 . 

When an iserver command is executed, either directly or via a user-defined 
command, the parameters are built up from 3 parts in the following order: 

1 The parameters supplied with the options command. 

2 The parameters entered on the command line by the user 

3 The parameters from the command definition (if a user-defined command). 
Example (UNIX based systems): 

If the following commands are executed in the session manager: 

# options -sb ilca.btl 

# iserver -si 42 tako.dat 

Then the following iserver command line is generated: 



iserver ■ -sb ika.bti; 



-si 42 tako.dat ■ 



Parameters from the Parameters from the 
options command command line 

Example (MS-DOS/VMS based systems): 

If the following commands are executed in the session manager: 

# options /sb ika.bti 

# iserver /si 42 tako.dat 
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Then the following iserver command line is generated: 



iserver • /sb ilca.bti; • /si 42 tako.dat; 

1 ...... I !„ . , i 

Parameters from the Parameters from the 
options command command line 

13.6.4 User-defined commands 

In addition to the built-in commands of the session manager, new commands can 
be defined by the user. These commands define a set of of parameters to be 
passed to the session manager iserver command, giving a shorthand for regu- 
larly used commands. 

New commands are defined in the session manager configuration file, named in 
the environment variable ISESSION, The commands are defined as a set of 
parameters to the session manager's iserver command. 

The format of the file is simple. Each command occupies a single line. The 
command name is the first word on the line. The rest of the line are the parameters 
to the iserver command that is to be substituted for the user-defined command. 

Asan example, suppose a program called mytool is normally booted onto a trans- 
puter with the SE and the SB options followed by user parameters for the tool. The 
normal iserver command line might look something like this: 

iserver -se -sb /usr/tpbin/mytool.b8h parameters (UNIX) 
iserver /se /sb /usr/tpbin/mytool. b8h parameters (MS-DOS/VMS) 

To simplify this inside the session manager, the following lines would be put in the 
session manager configuration file; 

mytool -se — sb /usr/tpbin/mytool. b8h (UNIX) 
mytool /se /sb /usr/tpbin/mytool. b8h (MS-DOS/VMS) 

Then, if the command 'mytool parameters 1 is entered on the session manager 
command line it will be replaced with the command: 

UNIX based systems: 
iserver ; parameters 



se -sb /usr/tpbin/mytool.bBh; 

■-.»»»-».»- _ _ : . _ J 

Parameters from Parameters from the 

the command line command definition 



MS-DOS/VMS based systems: 

r ----- 

iserver \ parameters 



; /se /sb /usr/tpbin/mytool. b8h; 
fc _ _ ________j 

Parameters from Parameters from the 

the command line command definition 
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The server command line is built up as described above in section 13.6.3 so, if 
some extra parameters are defined with the options command they will be 
included as well. For example, the command sequence: 

UNIX based systems: MS-DOS/VMS based systems: 

options -si options /si 

mytool parameters mytool parameters 

Would cause the following iserver command to be generated: 

iserver -si parameters -se -sb /usr/tpbin/mytool.bSh (UNIX) 
iserver / si parameters /se /sb /usr/tpbin/mytool.b8h 

(MS-DOS/VMS) 

Running the debugger from the session manager 

One important use of user defined commands in the session manager is to allow 
the debugger to be run. This is done by defining a command such as the following 
in the session manager configuration file. 

idebug -se -sb /usr/local/D5214/itools/idebug.btl (UNIX) 
idebug /se /sb /usr/local/D5214/itools/idebug.btl 

(MS-DOS/VMS) 

The exact form of this command will depend on which toolset is being used and 
the type of program being debugged. For more details on idebug command line 
options, see chapter 4. 

13,6.5 Host OS commands 

If a command is not one of the session manager's internal commands and not a 
user-defined command then it is passed to the host's operating system for execu- 
tion. 

13.7 Connecting transputers to computer networks 

Transputer systems may be connected to the host computer in a number of ways. 
For example, they may be connected directly to the host via a board such as the 
IMS BOOS motherboard, or via Ethernet using an IMS B300 TCPIink box. 1 

Each connection, however implemented, is treated in the same way. Programs can 
be loaded onto a transputer system via any of these connections and that program 
can then gain access to host facilities and communicate with the user via the same 
connection. Each of these connections is known as a user link. 

13.7.1 Capabilities 

User links are identified to users (and tools) by name. Each user link has one or 
more names, known as capabilities — the names should be chosen to indicate to 

Tltlsalso possible to remotely access a transputer directly connected to another (remote) host 
This requires the host connection server {HCS) to be running on the remote host — currently the 
HCS software is only available for PCs. 
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a user what type of transputer system is connected to that user link. Examples of 
capability names that might be used are B008, T801+2MB, or Grid; 10x10. 



Capabilities 

USERLINK1 

TBTorus 

T805 



Capabilities 

USERLINK2 

16bit^Transputer 

T2I2 



Capabilities 

USERLINK3 
3 2bit -Transputer 

T425 



Capabilities 

USERLINK4 

32bit-Transputer 

T800 



Figure 13.1 Capabilities for user links 

If access to a transputer system is desired, one of the capability names of a user 
link is given to the iserver. If a user link of that name is free then unique access 
to that user link is granted until the server terminates. If the session manager inter- 
face of the server is used (see Section 13.6), then unique access to the user link 
can be maintained for as long as required. If the capability specified is not unique 
then the iserver searches for the first free user linkon the local machine with that 
capability. If that capability is not available, remote machines are then searched. 
For this reason each user link will normally have several capabilities, at least one 
of which will be unique in the network. 

Figure 13.1 shows an example computer network with four user links. Each user 
link has several capabilities. If a specific user link is to be used then the capability 
USERLINK1, DSERLINK2 etc. should be used. If that user link is free unique 
access to it will be given, if all that is required is a 32 bit transputer {to run a tool, 
for instance) than the capability 32bit-Transputer could be used; connection 
to either of user links 3 or 4 could then be made, assuming that one of them is free. 

When the iserver is run it is given the name of a capability with the 'SL' option 
or the environment variable transputer. The server finds the information it 
needs to access that transputer network from the connection database file. 

13.7.2 The connection database 

Each transputer system available is described in the connection database file. The 
iserver, when given the name of a transputer system, uses the connection data- 
base to determine how to access that system. The name of the connection data- 
base file is defined by the environment variable icondb. 

The connection database is a text file which contains a description of all the avail- 
able capabilities. In a PC development system, for example, the connection data- 
base may contain only a single entry — the transputer board which is installed in 
the PC. In a multi-user development environment such as a networked Sun 
workstation, the database may contain a number of capabilities representing 
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transputer links connected directly to the host or accessible via Ethernet In this 
case the connection database will be set up by the system administrator. 

There may be several entries in the connection database with the same capability 
name. In this case, when a user runs iserver specifying this capability, the first 
system with that capability name which is not already in use will be allocated to the 
user. 

The connection database must exist for iserver to be able to access a trans- 
puter. The server uses the environment variable icondb to locate the connection 
database file. 

Examples and further details of the contents of the connection database are given 
in section 13.8. 



13.7.3 Using a specific node 

It is possible to request that a capability on a specific network node is used (note 
that 'node' in this context may be an IMS B300 Ethernet interface). To do this the 
character's' is added after the capability name, followed by the name of the node. 
When this is done the named node is contacted directly. If the specified capability 
is not tree on that node then the request will fail. 

For example, to use the capability T4-torus on the node pwllheli the name 
T4-torus@pwllheli would be specified to the server. 

The special name localhost is defined as being the the local host (alternatively, 
the local host's name may be used directly). If the local host is specified then only 
local user links may be used. If no suitable user link is found locally the request will 
fail. 

1 3.8 The connection database 

This section gives more detail about the connection database file that provides 
information to the server about the available transputer networks. 

13.8.1 Connection databases 

A connection database file must be available on your host before you can gain 
access to any user links. The connection database describes the transputer 
systems available on your network, The format of the connection database file is 
described below, in section 13.8.2. 

In a single-user system such as a PC-compatible development system, there may 
only be a single entry in the connection database file - this will describe the trans- 
puter board installed in the PC. A typical entry for an IMS BOOS board rn a PC might 
look like this: 

|B008|T|localhost|#150|b004j | |B008 with 3 x T805 | 
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In a larger development environment, there may be many entries describing all the 
transputer systems in the entire network of development systems. In this case, the 
connection database file will usually be created and managed by the system 
administrator. 

CapabiJity names 

There may be a number of different user Ifnks with the same name so that similar 
transputer systems can have the same capability. For example, all the user links 
which are connected to transputers which can run transputer based tools could be 
given the capability ToolHost. 

Similarly, there may be more than one entry for each transputer system in order 
to give multiple names to the same resource. This allows a transputer network with 
a 30MHzT805 transputer, for example, to be described with the capabilities Tool- 
Host (for user who want to use any transputer that can run transputer based tools) 
and T805-30 (for those who need to use that specific type of transputer). 



13.8.2 Connection database format 

Connection database files are ASCII text files. It can contain four types of line: 

• 3lank lines — these are ignored. 

• Lines starting with a '#' character are comment lines, and are ignored. 

• Lines starting with a ' | ' character are record lines, containing connection 
data. 

• Lines starting with a '*' character are continuation lines, used when a 
record line will not conveniently fit on one line. 

Records in the database are made up of eight fields, in a fixed order. Fields are 
separated by a ' | ' character. Records may be broken over a number of lines if 
required, but may only be broken between fields. In this case a '*' character is used 
as the field separator, and must appear at the end of the line to be continued, and 
as the first character on the continuation line. The characters ' \ r and '*' are not 
permitted within any field. Trailing spaces in a field are ignored. 

The fields are shown in Table 13.3. There are two field types, String and Boolean. 
A String is one or more ASCII text characters and a Boolean is a single ASCII char- 
acter, either 'f ' or T' for false or ( t' or Y for true. 
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Field 


Type 


Description 


Example 


Capability 


String 


Capability (Name) of user link 


T8-grid 


IsWorking 


Boolean 


True if the user link is available 


T 


Machine 


String 


Network name of host machine for 
that user link (localhost if local) 


pwllheli 


Linkname 


String 


Name of link connected to user link 


/dev/bxviO 


Linkdev 


String 


Type of device providing user link 


B016 


Mmsfile 


String 


Reserved for future use 




Mmslink 


String 


Reserved for future use 




Description 


String 


Comment describing user link 


T805 Square 
Grid 



Table 13.3 Connection database record fields 



13.8.3 Example connection databases 
PC development system 



The first example shows how 2 PC add-in boards in the same system could be 
described. Each board has two names: a common name (B008) to allow a user 
to access whichever user link is available, and a unique name to enable the user 
to specify which transputer system they wish to use (T400 or 1805). 

# The following resource describes a BOOS with a T400 . 

# The link device is at address #150. 

JT400 |T|localhost|#150|bOQ4| | |B00B board with T4Q0 +■ 2MB| 
[BOOS |T|localhost|#150|bQG4| | |B008 board with T400 +■ 2MB| 

# The following resource describes a BOOS with a T801 . 
f The link device is at address #200. 

ITS05 |T| localhost! #200 |b004 || IB008 board with T801 + 2MB[ 
JB008 |T| localhost] #200 |b004 | [ |B008 board with T801 + 2MB[ 
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Sun workstation 

This example shows how the various boards that can be connected to a Sun 
workstation directly, can be described in a connection database file. 

f Sample connection database. 

# The device names and addresses supplied are the default names 
f and/or addresses suggested in the installation section of the 
f board's manual. 

# The following resource allows access to a B011 connected to this 

# host. The resource name is "B011" and the device is accessed 

# at address 0x800000. 

|B011|Tflocalhost| 0x600000 | bOll | | jDescription of board| 

# The following resource allows access to a B014 connected to the 

# host. The resource name is "BQ14" and the B014 device driver is 
f accessed via "/dev/bativO" . 

IB014. |T|localhost|/dev/bxiv0|b014| | |Description of boardl 

# 

# The following resource allows access to a B016 connected to the 

# host. The resource names are "BQ16-0" to "BQ16-3" and the B016 

# device drivers are accessed via "/dev/bxviO" through to 

# "/dev/bxvi3". 

IB016-0 |T|localho3t]/dev/bxvi0|b0l6| | IDescription of boardl 

IB016-1 [T|localhostJ/dev/bxviljb016| | IDescription of boardl 

[B016-3 |T[localhost|/dev/bxvi2|b016| | jDescription of boardl 

IB016-4 |T]localhost[/dev/bxvi3|b016| | (Description of board] 

IMS B300 

The following example shows how four transputer systems available via Ethernet 
could be described. 

f Connection database for an IMS B300 with the node name 'billy' 

f A T425 connected to link 2 of the B300 
IHOSTLINK0 |T|billy|2|tcp| | |T425+1M| 
ITA |T|billy|2|tcp| | |T425+1M| 
IT425 |T|billy|2|tcp| [ |T425+1M| 

# A T805 connected to link 3 of the B300 
IHOSTLINK1 |T (billy |3jtcp| | |T805+2M| 

|TA |T|billy|3]tcp| | |T805+2M| 
JT805 |T|billy|3|tcp| I 1T805+2MI 

# Another TBQ5 connected to link of the B300 
IHOSTLIKK2 |T Ibilly \ | top | | |T805+2M( 

ITA |T|billylO|tcp| | |T805+2M| 
IT805 |T|billy|0|tcp| | |T805+2M| 

t A small network connected to link 1 of the B300 
IH0STLXNK3 |T|billy | 1 | tcp | | IT800+4M + T805+2M + T222+60K| 
ITA |T|billy|l|tcp| | [T800+4M + T805+2M + T222+60KI 
|T800 |T|billy|lJtcp| | IT800+4M + T305+2M + T222+60K| 
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13.9 New server features 

This section summarizes the main differences between version 1.5 of the 
iserver and previous versions. 

The new features are: 

• The addition of a session manager user interface. 

• A connection manager has been added, and capability names are used 
instead of link names. There is no longer a default name. 

• Some new command line options have been added. 

• User interrupt behavior has changed. 

• Exit codes have changed. 

• New error codes have been added. 

• Stream identifiers are validated. 

• Support for record structured files has been added. 

These changes are described in more detail in the following sections. 

13.9.1 Session manager 

This is a simple user interface that provides control of access to shared transputer 
resources. It will provide unique access to a specified transputer resource (if avail- 
able) for as long as required. See section 13.6. 

13.9.2 Connection manager 

The connection manager provides transparent access to both remote and local 
transputer resources. Resources are identified by a "capability name" and, option- 
ally, the name of the host to which the resource is connected. See section 13.7. 

13.9.3 New command line options 

Three new command line options have been added: 

sk Retry the connection at intervals. 

SM Invoke the session manager interface. 

ST All arguments which follow are not iserver arguments and will be 
passed to the application. Note that this is a significant change to the way 
that the iserver parses its command line. Existing command files or shell 
scripts may need to be changed. 

13.9.4 User interrupt 

Behavior on user interruption depends on how the server is being run. If the 
session manager interface is being used, then the server returns to the session 
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manager interface. If the session manager is not being used then the server termi- 
nates. 

13.9.5 Exit codes 

This version of the i server makes it possible to distinguish between the various 
causes of termination of the server, such as user break, error flag set etc. 
Appendix C provides full details of the exit codes. 

13.9.6 Error codes 

Server operations now return a range of error codes to indicate the cause of a 
failure. Checks are now made to ensure that operations are supported, a particular 
transputer system is available etc. 

Appendix G provides details of i server error codes. 

13.9.7 Stream identifier validation 

Checks have been added to the server to validate all stream identifiers. Earlier 
versions of the server assumed that a stream identifier would always be valid. 

13.9.8 Record structured file support 

Support for record structured files has been added for all supported hosts. 
Supported formats are formatted sequential, unformatted sequential, formatted 
direct and unformatted direct. See Appendix C for full details. 

13.10 Error messages 

A list of possible error messages which iserver may produce follows. In some 
cases, these messages may be followed by an extra message giving additional 
information; these are listed below in section 13.10.1. 

Aborted by user 

The user interrupted the server, by pressing [Ctii-CI or I Ctrl-Break! . 

Boot filename is too long, maximum size is number characters 

The specified filename was too long, number is the maximum size for file- 
names. 

Cannot find boot file filename 

The server cannot open the specified file. 

Command line too long (at string) 

The maximum permissible command line length has been exceeded. The 
overflow occurred at string. 
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Copy filename is too long, maximum size is number characters 

The specified filename was too Song, number \$ the maximum size for file- 
names. 

Error flag raised by transputer 

The program has set the error flag. Debug the program. 

Expected a filename after -SB option 

The 'SB 1 option requires the name of a file to load. 

Expected a filename after -SC option 

The l sc' option requires the name of a file to load. 

Expected a name after -SL option 

The 'SL 1 option requires a link name or address. 

Expected a number after -SP option 

The 'SP' option must specify the number of Kbytes to peek. 

Failed to allocate CoreDump buffer 

The 'sp' option was used but the server was unable to allocate enough 
memory to allow the transputer's memory to be copied. 

Failed to analyse root transputer 

The link driver could not analyze the transputer. 

Failed to reset root transputer 

The link driver could not reset the transputer. 

Reset and analyse are incompatible 

Reset and anatyze options cannot be used together. 

Timed out peeking word number 

The server was unable to peek the transputer. 

Transputer error flag has been set 

The program has set the error flag. Debug the program. 

Unable to access a transputer 

The server was unable to gain access to a link. This occurs when the link 
address or device name, specified either with the SL option or the TRANS- 
PUTER environment variable, is incorrect or does not exist. This message 
will be followed by one of the messages listed below. 
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Unable to free transputer link 

The server was unable to free the link resource because of a host error. The 
reason for the error will be host dependent. 

Unable to get request from link 

The server failed to get a packet from the transputer because of some 
general failure. 

Unable to write byte number io the boot link 

The transputer did not accept the file for loading . This can occur if the trans- 
puter was not reset or because the file was corrupted or in incorrect format. 



13.10.1 Additional error messages 

The following messages provide additional information to accompany error 
messages from the server 

: no environment variable ICOMDB 

There is no environment variable icondb. 

: can't open connection database file [...] 

The file specified in the environment variable ICONDB cannot be accessed. 

connection database, file [...], at line [...] 
-> premature end of file 

The database file is corrupt, a record line is not complete. 

connection database, file [...], at line [...] 
-> premature end of file, looking for field {..,} 

The database file is corrupt. A record line is not complete; the field {. ..} does 
not exist. 

connection database, file [...], at line [...] 
-> expecting continuation character 

Line [...] of the database file is corrupt. The record was not complete, a field 
is missing and there was no continuation indicating the record is continued 
on the next line. 

connection database, file[...] T at line[...] 

-> expecting continuation character at start of line, looking for field {...} 

Line [...] of the database file is corrupt. The previous line ended with a 
continuation character - a continuation was expected to start the current 
line. 
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connection database, file[...], at line[...] 

-> can't start a line with continuation, looking for field {...} 

Line [...] of the database file is corrupt. A record line started with a continua- 
tion character (it should start with a field separator). The {...} field was 
expected. 

connection database, file[...], at line[...] 
->bad field separator, looking for field {,..} 

Line [...] of the database file is corrupt; the field was illegal. 

connection database, file[...], at line[...] 
-> field {...} cannot be null 

Line [...] of the database file is corrupt. The field {...} contained a null value 
(this is illegal). 

connection database, file[...] f at line[...] 

-> illegal boolean value, looking for field {...} 

Line [...] of the database file is corrupt. The field {...} should contain a 
boolean value. 

connection database, file[...], at line[...] 
-> illegal linkdev field - unknown method 

Line [...] of the database file is corrupt. The Linkdev field should contain a 
link method value. 
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14 isim — T425 
simulator 



This chapter describes the T425 simulator tool isim that allows programs to be 
run and tested without transputer hardware. The chapter explains how to invoke 
the tool and describes the simulator commands that allow the simulated program 
to be debugged interactively. 



14.1 Introduction 

The simulator can run any transputer program that would run on a single IMST425 
mounted on a normal transputer evaluation board and supported by a host running 
iserver. No transputer hardware is required. 

Because the simulator runs the same code that would be loaded onto a real trans- 
puter, any program that runs satisfactorily in the simulator will run on an IMS T425. 
Because all 32-bit transputers are compatible at the source level, the same 
program can also be run on any INMOS 32-bit processor after recompiling for the 
correct processor type. 

The simulator also provides a reduced set of debugging facilities similar to those 
of the debugger Monitor page. Additional features provided by the simulator are 
the ability to set break points at simulated transputer addresses and to single step 
the program. The program should be loaded into memory (using the fol , |~J~| or 
j~p~l commands) before breakpoint debugging facilities are used. This ensures that 
breakpoints are not overwritten during the booting phase. 

The simufatorcan also be used to familiarize new users with transputers and trans- 
puter programming, and as a teaching aid. 



14.2 Running the simulator 

To run the simulator use the following command line: 

^ isim program [programparameters] { options } 

where: program is the program bootable file. 

programparameters is a list of parameters to the program. The list of 
parameters may follow the isim 'N' option and parameters must be sepa- 
rated by spaces. See section 14.2.1. 
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options is a list of options from Table 14,1 . 



Options must be preceded by '-' for UNIX-based toolsets and y for 
MS-DOS and VMS based toolsets. 

Options may be given in any order. 

Options may be entered in upper or lower case and can be given In any 
order 



Only one filename may be given on the command line. 

If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Option 


Description 


B 


Batch mode operation. The simulator runs in line mode i.e. fuEl 
display data is not provided. Commands are read in from the input 
stream e.g. the keyboard and executed. The commands are not 
echoed to the output stream e.g. the display screen, as they are 
executed. 


BQ 


Batch Quiet mode. The simulator automatically executes the 
program sp oified on the command line and then terminates. If an 
error occurs, the appropriate message will be displayed. The 
debugging facilities of the simulator are not available in this mode. 


BV 


Batch Verify mode. Similar to batch mode, except that the 
commands and prompts displayed when running the simulator in 
interactive mode are echoed to the output stream e.g. the display. 


I 


Displays information about the simulator as it runs. 


N 


No more options for the simulator. Any options entered after this 
option wilt be assumed to be program parameters to be passed to 
the program running on the simulator. 



Table 14.1 islm options 



14.2.1 Passing in parameters to the program 

Program parameters can be passed to programs which are simulated on any host. 
Parameter passing is equivalent to running a transputer bootable program using 
i server. 

isimwill normally parse the command line and any options it recognizes as its own 
will not be passed to the user program. In cases where options are required for a 
user program which clash with one of the isim options the *N' option can be used. 
After the 'N' option isim ceases parsing the command line for its own options; the 
remainder of the command line is simply passed through to the user program. 
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14.2.2 Example of use 

isim hello. btl 
This invokes the simulator on the 'Hello World' program. 

When first invoked the simulator enters the debugging environment. To start the 
program invoke the 'G' command. Then press [return] in response to the 
"break point address" prompt. The program then runs until it completes 
successfully, a runtime error occurs, or a break point is reached. If an error occurs 
the processor halts, the error flag is set, and the program can be debugged using 
commands to examine memory and registers. 

When invoked with the 'BQ' option (Batch Quiet) the simulator immediately runs the 
program and does not enter the debugging environment. 

isim -bq hello. btl (UNIX based toolsets) 

isim /bq hello .btl {MS-DOS and VMS based toolsets) 

14.2.3 ITERM file 

The simulator reads the ITERM file to determine how to control the terminal screen 
and to map a few simulator commands. The ITERM file must be defined in the host 
environment variable ITERM. See appendix D. 

14.3 Monitor page display 

The simulator Monitor page is similar to that of the debugger, which is described 
in chapter 4. Data displayed at the simulator Monitor page includes: 



Iptr 

Wfc>tr 

Error 

Halt On Error 

Fptrl 

Bptrl 

E^trO 
BptrO 

TPtrl 

TPtrO 



Contents of instruction pointer (address of the next instruction 
to be executed). 

Contents of workspace pointer. 

Status of error flag. 

Status of halt on error flag. 

Pointer to the front of the low priority active process queue. If 
'jump 0' breaks are enabled the letter B is displayed after the 
pointer value. 

Pointer to the back of the low priority active process queue. 
Pointer to the front of the high priority active process queue. 
Pointer to the back of the high priority active process queue. 

Pointer to the low priority timer queue. If the timer is disabled 
the letter X is displayed after the pointer value. 

Pointer to the high priority timer queue. 



Note: If Wptr contains the most negative address value, it will be described as 
'invalid'. This normally means that no process is executing in the simulator (for 
example, the program may have become deadlocked). 
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The Monitor page also displays the last instruction executed , a summary of Monitor 
page commands, and, if an error has occurred, the cause of the error. 



14.4 Simulator commands 

All simulator commands are given at the Monitor page. Many of the commands are 
similarto those of the idebug Monitor page, however, there are a number of imple- 
mentation differences. Full descriptions of the commands are given in the following 
sections. 



14.4.1 Specifying numerical parameters 

Some simulator commands require numerical parameters, such as addresses. 
These can be specified as simple expressions in decimal or hexadecimal format. 
Expressions can be the sum of two expressions, the result of subtracting one 
expression from another, or constants. Constants that can be specified are: Areg, 
Breg, Creg, Iptr, Wptr, decimal constants, hexadecimal constants, or abbre- 
viated hexadecimal constants. 

Hexadecimal constants are specified using the prefix #. Abbreviated hex constants 
can be created by prefixing the sequence of hex digits with '%', which assumes the 
hexadecimal prefix '800 o + . .'. For example, the abbreviation *%F8A' is interpreted 
as the hex number '8000F8A'. 



14.4.2 Keys mapped by ITERM 

Several commands for controlling the display are mapped to specific keys by the 
ITERM file, see appendix D. Key mappings for specific terminal keyboards can be 
found in the Delivery Manual, 

[HELP | Displays help information. 

| refresh^ Re-draws the screen. 

[ FINISH | Quits the simulator. 

I page UP | Scrolls the current display. 

| PageDown"! Scrolls the current display. 

[XI , |~Tl Scrolls the current display. 
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14 A3 Command summary 


Key 


Meaning 


Description 


A 


ASCII 


Displays a portion of memory in ASCII. 


B 


Break points 


Breakpoint menu. 


D 


Disassemble 


Displays transputer instructions at a specified area 
of memory. 


G 


Go 


Runs (or resumes) the program. 


H 


Hex 


Displays a portion of memory in hexadecimal. 


I 


Inspect 


Displays a portion of memory in any occam type. 


J 


Jump into 
program 


Runs (or resumes) the program. Same as G. 


L 


Links 


Displays Iptr and Wptr for processes waiting for 
input or output on a link, or for a signal on the 
Event pin. 


M 


Memory map 


This option is not supported for the current toolset. 


N 


Create dump fife 


Creates a core dump file. 


P 


Program boot 


Simulates a program 'boof onto the transputer. 


Q 


Quit 


Quits the simulator. 


R 


Run queue 


Displays iptr and Wptr for processes on the high 
or low priority active process queues. 


S 


Single step 


Executes the next transputer instruction. 


T 


Timer queue 


Displays Iptr, Wptr, and wake-up times for 
processes on the high or low priority timer queues. 


U 


Assign register 


Assigns a value to a register. 


? 


Help 


Displays help information. 



Table 14.2 Simulator commands 

14.4.4 Command descriptions 

[X] — ASCII 

This command displays a segment of transputer memory in ASCIt format, starting 
at a specific address. If no address is given the default address Wptr is used. 
Specify a start address after the prompt: 

{Start address (Wptr)) ? 

E ither press | return | to accept the default address, or enter the desired add ress. 
The address can be entered as a decimal number, a hexadecimal number 
preceded by '#', or the short form '%h. . *ti. 
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The memory is displayed in blocks of 13 rows of 32 ASCII bytes, each row 
preceded by an absolute address in hexadecimal. Bytes are ordered from left to 
right in each row. Unprintable characters are substituted by a full stop, 

Tne (E» [£» | page up | , and | PAGEDOWN"] keys can be used to scroll the 
display. 

[~b~1 - Breakpoints 

Sets, displays, and cancels break points at specified memory locations or proce- 
dure calls. The program should be loaded into memory (using thefG], [7] orfPl 
commands) before this command is used to set breakpoints. (The QT] command 
may also be used prior to this command, to determine where to set breakpoints). 

The command displays the Breakpoint Options Page: 

Breakpoint Options Page 

1) Set breakpoint at Address 

2} Display breakpoints 

3) Cancel breakpoint at Address 

Select Option? 

Options are selected by entering one of the single digit commands. The following 
prompts are displayed depending on the command selection: 

Command Prompt 

1 (break address) ? 

3 (break address (ALL) } 



Pressing | return | with no typed input in response to command 1 cancels the 
option; in response to command 3, it causes alt breakpoints to be cancelled. 

After each breakpoint command the user is returned to the simulator command 
prompt. 

[d] -Disassemble 

The Disassemble command disassembles memory into transputer instructions. 
Specify an address at which to start disassembly after the prompt: 

(Start address (Iptr)) ? 

Either press | RETURN | to accept the default address, or enter the desired address. 
The address can be entered as a decimal number, a hexadecimal number 
preceded by '#', or the short form '%h. . ,h\ 
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The memory is displayed in batches of thirteen transputer instructions, starting 
with the instruction at the specified address. If the specified address is within an 
instruction, the disassembly begins at the start of that instruction. Where the 
preceding code is data ending with a transputer 'pfix' or 4 nf ix 1 instruction, disas- 
sembly begins at the start of the pf ix or nf ix code. 

Each instruction is displayed on a single line preceded by the address corre- 
sponding to the first byte of the instruction. The disassembly is a direct translation 
of memory contents into instructions; it neither inserts labels, nor provides 
symbolic operands. 

The [ij, [▼], I PAG £ up 1 > and | PAGEDOWN "] ke y s can be used to scro11 * ne 
display. 

[G] -Go 

Starts the program, or continues running the program after a breakpoint or error 
has been encountered. The program will run until it completes successfully, sets 
the error flag, or reaches a break point. 

To start the program, specify a break point address after the following prompt and 
press | return j: 



(break point address) 
The default is not to set a break point. 

pH~l-Hex 

The Hex command displays memory in hexadecimal. Specify the start address 
after the prompt: 

(Start address (Wptr) ? 

Press | return | to accept the default address, or enter the desired address. The 
address can be entered as a decimal number, a hexadecimal number preceded 
by '#', or the short form ( %h, , ,h'. If the specified start address is within a word, the 
start address is aligned to the start of that word. 

The memory is displayed as rows of words in hexadecimal format. Each row 
contains four words of eight hexadecimal digits, with the most significant byte first. 

Words are ordered left to right in the row starting from the lowest address. The word 
specified by the start address is the top leftmost word of the display. 

The address at the start of each line is an absolute address displayed in hexade- 
cimal format 
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[T1 - Inspect 

Displays a portion of memory in any occam type - as defined in the 'occam 2 
Reference Manual'. 

The Inspect command can be used to inspect the contents of an entire array. 

Specify a start address after the prompt: 

(Start address (Wptr) ) ? 

Either press | RETURN | to accept the default address, or enter the desired address. 
The address can be entered as a decimal number, a hexadecimal number 
preceded by 'f, or the short form '%h. . .h\ 

When a start address has been given, the following prompt is displayed: 

Typed memory dump 

- ASCII 

1 - INT 

2 - BYTE 

3 - BOOL 

4 - IHT16 

5 - INT32 

6 - I NT 6 4 (Not implemented} 

7 - REAL32 (Not implemented} 

8 - REAL64 (Not implemented} 

9 - CHAN 

Which occam type ? 

Give the number corresponding to the type you wish to display or press [return [ 
to accept the default type. Initially the default will be HEX; for subsequent use of 
the command the default takes the value of the last selected type, 

ASCII arrays are displayed in the format used by the Monitor page command 
'ASCII'. Other types are displayed both in their normal representation and hexade- 
cimal format. 

The memory is displayed as thirteen rows of data. The address at the start of each 
line is an absolute address displayed as a hexadecimal number. The element 
specified by the start address is on the top row of the display. 

Start addresses are aligned to the nearest valid boundary for the type , that is: BYTE 
and BOOL to the nearest byte; INT16 to the nearest even byte; int, INT32 and 
CHAN to the nearest word. 

|~J~1 - Jump into program 

Same as [G] - starts or continues running the program. 
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\T] -Links 

Displays information about simulated Links. 

The Links command displays the instruction pointer Iptr, workspace descriptor 
wdesc and priority, of the processes waiting for communication on a link, or for a 
signal on the Event pin. If no process is waiting, the link is described as 'Empty 1 . 
Link connections on the processor, and the link from which the processor was 
booted are also displayed. 

The format of the display is similar to the following: 

(Lo) 



Link out Iptr: #80000256 


Wdesc: 


#80000091 


Link 1 out Empty 






Link 2 out Empty 






Link 3 out Empty 






Link in Empty 






Link 1 in Empty 






Link 2 in Empty 






Link 3 in Empty 







Link connected to Host 
Links 1, 2 r 3 not connected 

Booted from link 

[W\ -Memory map 

This option is not applicable to the current version of isim, if used the following 
message will be displayed: 

Memory Map Invalid 

[W] - Create dump file 

Creates a core dump file from which the program can be debugged off-line. The 
name of the file and the number of bytes to write must be specified. A file extension 
is not required and should not be specified. The dump file is automatically given 
the .dmp extension. This can be used by idebug, see chapter 4. 

|~p~| - Program boot 

Loads the program into transputer memory ('boots the program') so that debug- 
ging can start at beginning of the application program without stepping through 
bootstrap loading code. The program is loaded into memory but is not automati- 
cally run. This command can only be used prior to executing any other instructions, 

fo"! -Quit 

Quits the simulator, and returns to the host operating system, 
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|~R] -Run queues 

This command displays Iptrs and wdescs for processes waiting on the proces- 
sor's active process queues. If both high and low priority front process queues are 
empty, the following message Is displayed: 

Both process queues are empty 

if neither queue is empty, you are required to specify the queue: 

High or low priority process queue ? (H,L) 

Type 4 H' or 'L* as required If only one queue is empty isimdisplays the non-empty 
queue. 

The [X|i \T}* | page UP | , and | PAGEDOWN [ keys can be used to scroll the 
display. 

|~S~| - Single step transputer instruction 

This command executes the transputer instruction pointed to by iptr. By 
repeating the command the user may single step through the program, observing 
the changes to the process queues and registers, as the display is updated. 

rn - Timer queue 

This command displays Iptrs, Wdescs, and wake-up times for processes waiting 
on the processor's timer queues. Prompts and displays are similar to those for the 
Run queue command. 

\TT\- Assign 

Assigns a value to a register, iptr orwptr. To assign a value, specify the register 
by name (abbreviations are permitted), and give a value to be assigned to the 
register. This enables the program to be re-run (using QT] or [7] ) with alternative 
values in the registers. 

| help | 
\T\ — Help 

Lists the available simulator commands. 



REFRESH I - Refresh 



Refreshes the screen. 
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FINISH I - Quit 



Quits the simulator, and returns to the host operating system. 

The ffli S- I PAGE up I . and | PAGEDQWN"| keys can be used to scroll the 
display. 

14.5 Batch mode operation 

isim can be run in batch mode by setting up the environment variable isim- 
batch. If this variable is defined on the system isim automatically selects batch 
mode operation. 

14.5.1 Setting up ISIMBATCH 

ISIMBATCH is set up on the system as an environment variable using the 
appropriate command for your host system. 

VERIFY and NOVERIFY modes which enable and disable the output of input 
commands and user responses are defined by setting a value for ISIMBATCH. In 
MS-DOS the command to use is the set command. For example: 

C:\ set ISIMBATCH=VERIFY 
C:\ set ISIMBATCH^KOVERIFY 

In UNIX the equivalent command is setenv and on VMS systems the command 
to use is define. Details of how to use these commands can be found in the user 
documentation for your system. 

14.5.2 Input command files 

In batch mode isim is driven from a command script containing simulator 
commands and responses to prompts. All prompts by isim must be followed by 
a valid response. 

14.5.3 Output 

Output can be written to a log file or displayed at the terminal. Input and output 
streams can be assigned to files or the user's terminal by commands on the host. 

isim can be set up to operate in VERIFY or NOVERIFY mode by setting a different 
values for ISIMBATCH. In VERIFY mode all prompts and user responses are 
included in the output. 

14.5.4 Batch mode commands 

Batch mode simulator commands 'A' through 'U' are the same as the interactive 
debugging commands. Two additional commands generate special batch mode 
output; 
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Key 


Meaning 


Description 


? 


Query state 


Displays values of registers and queue pointers. 


■ 


Where 


Displays next iptr and transputer instruction. 



PH - Query state 

Displays information about the processor state, including current values of regis- 
ters, queue pointers, and error flag status. For example: 

Processor state 

Iptr #80000070 

Wptr #300000C8 

Areg #60000070 

Breg #80000008 

Creg #80000010 

Error Clear 
Halt on Error Set 

Fptrl (Low #00000000 

Bptrl queue) #00000000 

FptrO (High #00000000 

BptrO queue) #00000000 

Tptrl (timer #2D2D2D2D 

TptrO (queues #2D2D2D2D 

□ -Where 

Displays the iptr of the next instruction to execute and a disassembly of that 
instruction. For example: 

Iptr #80000070. Low Priority, Hext Instruction : ajw 42 - #2A 



14.6 Error messages 
Cannot open bootfile 'filename' 

The file containing the code to be run could not be opened or could not be 
found. 

Environment variable 'IBOARDSIZE' does not exist 

Board memory size must be specified to the system using the the host envi- 
ronment variable IBOARDSIZE. Details of how to set up IBOARDSIZE on 
your system can be found in the Delivery Manual. 

Environment variable 'ITERM' not set up 

The ITERM definition file for the simulator function keys must be specified 
in the ITERM host environment variable. 
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IBOARDSIZE is too small (at least number bytes required) 

The simulator requires a minimum memory size in order to run correctly. 
Modify IBOARDSIZE and retry the command. 

ITERM error 

Iterm initialisation has failed 

The ITERM file for setting up the terminal codes is invalid. ITERM error 
describes the fault in the file. 

Simulator terminated: Error flag set - message 

Simulator messages may be output when the simulator halts (i.e. as an 
error condition), message can be one of: 

arithmetic overflow 
arithmetic underflow 
long overflow 
subscript out of range 
count out of range 
check single 
check word 
arithmetic exception 
floating point error 

Simulator terminated: message 

Simulator messages may be output when the simulator halts, due to an 
invalid operation within the program being simulated, message can be one 
of: 

attempt made to input from non-existent hard channel 

Attempt to input from output link, 
attempt made to output to non-existent hard channel 

Attempt to output to input link. 
attempt to output to unattached hard channel 

Attempt to output on unattached link. 
attempt to read illegal memory byte at address 

The memory address specified is invalid (not within iboardsize). 
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attempt to read Illegal memory word at address 

Invalid memory address or attempt to access non word aligned. 
attempt to set illegal memory byte pointer 

Invalid memory address (not within ibqardsize). 
attempt to set illegal memory word pointer 

(nvalid memory address or attempt to access non word aligned. 
attempt to write illegal memory byte at address 

Invalid memory address (not within ibqardsize). 
attempt to write illegal memory word at address 

Invalid memory address or attempt to access non word aligned. 

high priority process restored from save area 

A swapped out low priority process has been written over during an inter- 
rupt 

illegal operand (nnn) to operate command 

An attempt has been made to execute invalid instruction for the T425, 
input from iserverwhen iserver outputting 

I SERVER packet input before leading output sent, 
inputting [server packet larger than expected 

Illegal ISERVER protocol packet on input, 
output iserver packet larger than expected 

Illegal ISERVER protocol packet on output 
output to iserverwhen iserver inputting 

ISERVER packet output before response to last output received. 
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This chapter describes the skip loader tool that allows programs to be loaded onto 
transputer networks over the root transputer The tool sets up a data transfer 
protocol on the root transputer that allows programs running on the rest of the 
network to communicate directly with the host 

15.1 Introduction 

The skip tool iskip prepares a network to load a program over the root transputer 
by setting up a transparent route-through process on the root transputer to transfer 
data from the application program running on the target network to and from the 
host computer. A subsequent call to iserver loads the program onto the network 
connected to the root transputer, but does not use the root transputer as part of the 
network. The root transputer is in effect rendered transparent to the rest of the 
network. The route-through process uses a simple protocol that transfers data byte 
by byte between the program and the host. 

After iskip has been invoked to set up the data link across the root transputer, 
the program can be loaded down the host link using iserver. iskip can be used 
to skip any number of processors and load a program into any part of a network 
see section 15.2.2. 

iskip itself may only be executed on 32 bit transputers which have more than 8 
Kbytes of memory, although it may be used to reach both 1 6 and 32 bit transputers 
for target program execution. 

1 5.1 .1 Uses of the skip tool 

The skip tool has two main uses : 

1 To allow programs configured for specific arrangements of transputers to 
be loaded onto the target network without using the root transputer to run 
the program. The root transputer helps to load the program onto the 
network and subsequently provides a route-through process which trans- 
fers data from the application program to the host. 

Example of boards supplied by INMOS that can be used to skip load 
programs are the IMS B004 PC add-in board, which contains a single IMS 
T414 transputer, and the IMS B008 PC motherboard fitted with a TRAM in 
slot zero to act as the root transputer. Other slots on the motherboard can 
be used to accommodate the target network. 

2 Programs configured for a network that normally incorporates the root 
transputer can be debugged without having to use idump to save root 
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transputer's memory to disk. Programs can be loaded into the network 
connected to the root transputer and the debugger can safely run on the 
root transputer without overwriting the program. The external network must 
have the correct number and arrangement of processors and memory for 
the program to be loaded. 

This can make debugging transputer programs easierwhenan extra trans- 
puter is available. 



15*2 Running the skip loader 

To invoke the iskip tool use the following command line: 

P* iskip linknumber {options} 



where: linknumber is the link on the root transputer to which the target transputer 
network is connected. 

options is a list, in any order, of one or more options from Table 15.1. 



Options must be preceded by •-■ for UNIX-based toolsets and '/' for 
MS-DOS and VMS based toolsets. 

Options may be given in any order 

Options may be entered in upper or lower case. 



If no arguments are given on the command line a help page is displayed giving the 
command syntax. 



Option 


Description 


E 


Directs iskip to monitor the subsystem error status and termi- 
nates when it becomes set. 


I 


Displays detailed progress information as the tool loads. 


R 


Reset subsystem. Resets all transputers connected downstream of 
link linknumber. Does not reset the root transputer. 


RP 


A replacement for the R option when running programs on boards 
from certain vendors. 

Contact your supplier to see whether this option is applicable to 
your hardware. It does not apply to boards manufactured by 
INMOS. 



Table 15.1 iskip options 



72TDS367Q1 



March 1993 



15 iskip - skip loader 



287 



15.2.1 Skipping a single transputer 

This example illustrates how to use iskip to skip over the root transputer for the 
example network shown in Figure 15.1. 
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Figure 15.1 Skipping a single transputer 

For further information about subsystem wiring see chapter 7 in the User Guide 
and the debugger documentation in chapter 4 of this manual. 

Subsystem wired down: 

iskip 2 -r (UNIX based toolsets) 

iskip 2 /r (MS-DOS/VMS based toolsets) 

In this example iskip is invoked for a network where the subsystem is wired 
down. The network is prepared to load the program over the root transputer, which 
is connected to the network via link 2; the 'r' option resets the target network- 
Subsystem wired subs: 

iskip 2 -r -e (UNIX based toolsets) 

iskip 2 /r /e (MS-DOS/VMS based toolsets) 

In this example iskip is invoked for a network where the subsystem is wired subs. 
The V option has been added to the example, to direct iskip to monitor the 
subsystem error status, see section 15.2.4. 

15.2.2 Skipping multiple transputers 

This example illustrates how to use iskip to skip over two transputers (starting 
with the root transputer) for the example network shown in Figure 15.2. 
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Figure 1 5.2 Skipping over two transputers 
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Normally iskip is invoked via its driver program; this resets the root transputer 
and loads the transputer bootable image iskip . btl onto the transputer (essen- 
tially it performs an iserver -se -sb iskip. btl operation). Note: because 
the root transputer is reset, running iskip twice in succession will not achieve any 
more than running iskip once; the second invocation will reset the first and load 
iskip onto the root transputer. En order to skip over more than one transputer, 
iskip must be loaded onto subsequent transputers by a 'different' method that 
does not involve resetting the root transputer. This is best illustrated by an example 
as shown below (for a network wired subs): 

iskip 2 -r -e (UNIX based toolsets) 

iserver -se -ss -sc iskip. btl 

iskip 2 /r /e {MS-DOS/VMS based toolsets) 

iserver /se /ss /sc iskip. btl 

iskip . btl is the transputer bootable component of iskip, it may be found in the 
tools directory of this toolset release. For details of toolset directories see the 
delivery manual supplied with this toolset. 

15.2.3 Loading a program 

Once iskip has been invoked to prepare the network, the program is loaded by 
invoking iserver with the 'SE', ( SS' and 'SC 1 options, iserver must be invoked 
with the 'se 1 option if the error flag is required to be monitored. This applies whether 
the iskip *E' option is used or not For example: 

iserver -se -ss -sc myprog.btl (UNIX toolsets) 
iserver /se /ss /sc myprog.btl (MS-DOS/VMS toolsets) 

Note: After using the skip tool the root transputer must not be reset or analyzed, 
that is, iserver must not be invoked with the 'SR', 'SB', or 'SA' options, while 
iskip is required to run. 

15.2.4 Monitoring the error status - option E 

The iskip *E* option should only be used when the sub-network is connected to 
the Subsystem port of the root transputer i.e. *wired subs '. When the sub-network 
is connected to the Down port on the roottransputeri.e. 'wired Down \ the 'E' option 
must not be used. 

The 'E' option instructs iskip to monitorthe subsystem error status and terminate 
when It becomes set. When it terminates it sets its own error flag in order that the 
server may detect that an error in the subsystem has occurred. This allows the 
program to be debugged. 

If the subsystem error status is not properly monitored when the program is run, 
the server may become suspended when a program error occurs. In these circum- 
stances the server can be terminated using the host system BREAK key. 
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Note: There is a delay of one second after iskip is invoked with the 'E' option 
before monitoring ofthe subsystem error status begins; if the program fails before 
this the server may not terminate correctly and the host system BREAK key should 
be used. 



15.2.5 Clearing the error flag 

ff either iskip or iserver detect that the error flag is set immediately a program 
starts executing it is likely that the network consists of more processors than are 
currently being used and that one or more ofthe unused processors has its error 
flag set. 

On transputer boards the network may be reset using network check programs, 
such as ispy, which clear all error flags. 

The ispy program is provided as part ofthe support software for some INMOS k\ 
systems products. These products are available separately through your local 
INMOS distributor. 

An alternative to using a network check program to clear the network is to load a 
dummy process onto each processor. In the act of loading the process code the 
error flag is cleared. 



15.3 Error messages 

This section lists error messages that can be generated by the skip tool. 
Called incorrectly 

Command line error. Check command line syntax and retry. 
Cannot read server's command line 

Syntax error. Retry the command. 
Duplicate option: option 

option was supplied more than once on the command line. 
No filename supplied 

No filename was supplied on the command line. 
This option must be followed by a parameter: option 

The option specified requires a parameter. Check syntax and retry. 
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Unknown option: option 

The specified option is invalid. Check option list and retry. 

You must specify a link number (0 to 3) 

A link number is required. Specify the number of the root transputer link to 
which the network is connected. If you specify the host link an error is 
reported. 
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A Toolset conventions 
and defaults 



This appendix describes the standards and conventions used by INMOS toolsets 
for 

• Command line syntax 

• Filenames 

• Search paths 

• Fite extensions 

• Error message format 

A.1 Command line syntax 

All tools in the toolsets conform to a common command line format. 

A.1.1 General conventions 

• Commands, and their parameters and options, obey host system stan- 
dards. 

• Filenames, either directly specified on the command line or as arguments 
to options, must conform to the host system naming conventions. 

• Options must be prefixed with the standard option prefix character for the 
operating system {'-* for UNIX based toolsets and 7 'for VMS and MS-DOS 
based toolsets). 

• Command line parameters and options can be specified in any order but 
must be separated by spaces. 

• Lists of arguments to options, where allowed, must be enclosed in paren- 
theses, and the items in the list must be separated by commas. 

• If no parameters or options are specified the tool displays a help page that 
explains the command syntax. 

A.1.2 Standard options 

Standard command line options used in the toolsets have the same action for all 
tools. Standard options and their descriptions are given below. 
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Option 


Description 


F 


Specifies an indirect file (command script). 


I 


Displays progress data in full. 





Specifies an output file. 



A.2 Unsupported options 

A number of tools have various command line options beginning with 'z'. These 
options are used by 1NMOS for development purposes and have not been 
designed for users. As such they are unsupported and should not be used. INMOS 
cannot guarantee the results obtained from such options nor their continued pres- 
ence in future toolset releases. 



A.3 Filenames 

File names generally follow the naming and character set conventions of the host 
operating system except that the following directory separator characters cannot 
be used within a filename: 

• Colon V 

• Semi-colon';' 

• Forward slash "/' 

• Backslash 'V ('¥' for Japanese MS-DOS) 

• Square brackets '[]' 

• Round brackets ' ( } ' 

• Angle brackets '<>' 

• Exclamation mark ' ■ ' 

• Equals sign '=' 



A.4 Search paths 

The tools locate files by searching a specified directory path on the host system. 
The path is specified using the host environment variable ISEARCH. The search 
rules for all tools are as follows: 

1 If the filename contains a directory specification then the filename is used 
as given. Relative directory names are treated as relative to the directory 
in which the tool is invoked. 
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2 If no directory is specified the directory in which the tool is invoked is 
assumed. 

3 If the file is not present in the current directory, the path specified by the 
environment variable (or logical name) ISEARCH is searched. If there are 
several files of the same name on this path, the first occurrence is used. 

4 If the file is not found using the above rules, then the file is assumed to be 
absent, and an error is reported. 

If no search path has been set up then only rules 1 and 2 apply. 

By default all files are written to the current directory, 

A. 5 Standard file extensions 

The INMOS toolsets use a standard set of file extensions for source and object 
files. In most cases these extensions must be specified on the command line for 
input files. They are automatically created for output files, unless an alternative file- 
name is specified on the command line. 

A separate set of extensions for object files must be used where imakef is used 
to build programs for mixed processor networks. These are described separately 
in section A.6. 
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A.5 Standard file extensions 



A. 5.1 Main source and object files 



Extension 


Description 


.btl 


Bootable file which can be loaded onto a transputer or transputer 
network. Created by icollect directly from a .lku file {single 
transputer programs) or from a . cfbfHe. Bootable files can be sent 
down a link by iserver for immediate execution. Contains 
information used by iserver to control the host link for execution. 
AJso read by idebug*. 


.c 


C source files. Assumed by ice, the ANSI C compiler 


.cfb 


Configuration binary file containing a description of how code is to 
be placed on a network, a description of the route to be used to load 
the network, and the parameters to be passed to each of the 
processes. Created by the configurer from a user-defined configu- 
ration description and read by icollect to prepare a bootable file 
and by idebug* to load a network for debugging. 


.cfs 


Configuration description file. This is a text file, created by the user 
and describes the hardware and software networks and the 
mapping between them, It also references the linked units and is 
used as input to the C configurer icconf . 


.f77 


FORTRAN source files. Assumed by if77, the FORTRAN-77 
compiler. 


.h 


Header files for use in C source code. 


.lku 


Linked unit. Created by ilink as an executable process with no 
external references. Used as input to icollect (single transputer 
programs) or within a configuration description. Also read by 
idebug*. 


.lib 


Library file containing a collection of binary modules. Created by 
ilibr. 


.occ 


occam source files. Assumed by oc, the occam 2 compiler. 


.pgm 


Occam configuration description file. This is a text File, created by 
the user and describes the hardware and software networks and 
the mapping between them. It also references the linked units and 
is used as input to the occam configurer occonf . 


* tco 


Compiled binary module produced by all INMOS TCOFF 
compilers. Used as input to ilink and ilibr. Also read by 
idebug*. 


* Not applicable to the FORTRAN toolset 
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A.5.2 Indirect input files (script files) 



Extension 


Description 


.inc 


Include files named in #include compiler directives for occam, 
or finclude statements in configuration descriptions or in 
FORTRAN-77 statements. 


,lbb 


Library build files which specify the components of a library to 
ilibr. 


,liu 


Library usage files. Created and used by imakef . 


,lnk 


Linker indirect files which specify the components of a program to 
be linked. Also used by imakef when creating Makefiles, 



A,5.3 Files read by the memory map tool imap 



Extension 


Description 


.suae 


Map file output by the compiler. The characters 'xx'are determined 
by the 2nd and 3rd characters of the extension given to the compiler 
object file. For example if the compiler object file takes the default 
extension . tco, the information file is given the extension .ico. 


.dxx 


Map file output by the linker. The characters 'xx'are determined by 
the 2nd and 3rd characters of the extension given to the linker 
object file. For example if the linker object file takes the default 
extension . Iku, the information file is given the extension . dku. 


.map 


Map file output by the collector. 


Note: These extensions also satisfy imakef 's requirements, see section A.6. 



A.5.4 Other output files 



Extension 


Description 


.bin 


Binary format files produced by ieprom for loading into ROM. 


.btr 


Executable code without a bootstrap. Created by icollect and 
used as input to ieprom. 


.clu 


Configuration object file, created by the Occam configurer 
occonf. 


.hex 


A hex dump of a file for loading onto a ROM by a custom ROM 
loader tool. 


. ihx 


Intel hex format files produced by ieprom for loading into ROM. 


.mot 


Motorola 'srecord' files produced by ieprom for loading into ROM. 


.rsc 


An . rsc file contains the code of a process together with a descrip- 
tion of its requirements for data areas and parameters. It is created 
by the collector from a linked unit. The format is described in 
chapter 3. . rsc fifes are suitable for using with either the Occam 
or C functions which support dynamic code loading. 
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A.5.5 Miscellaneous files 



Extension 


Description 


. dnip* 


Memory dump and network dump files. Created by idump for 
debugging code on the root transputer (memory dump) or by 
idebug for off-line analysis of a program on a network (network 
dump). Read by the debugger for post-mortem debugging. 


. itm 


ITERM files containing information about the terminal. Used by 
tools such as idebug to handle the screen in a device-independent 
manner Can also be created by users for other terminals. The file 
is referenced via the environment variable iterm. 


.mak 


Makefile generated by imakef. This file may be input to a "make" 
utility to build the target file. May also be edited by the user. 


* Not applicable to the FORTRAN toolset 



A,6 Extensions required for imakef 

The standard set of file extensions are adequate for simple programs executing 
on a single transputer, or on a network of transputers all of the same type. If the 
network is heterogeneous and a particular source file needs to be compiled for 
more than one transputer type, the following scheme can be used to identify the 
individual processor types and error modes. 

If imakef is used to build the program, this scheme must be used. 

The extended system uses extensions of the form . fpe: 

where: f denotes the type of file and can take the following values: 

t for . tco equivalents. 

1 for . ink equivalents. 

c for . lku equivalents. 

r for . rsc equivalents. 

p denotes the transputer target type or class. This can take the 
following values: 

2-T212,T222, M212 

3-T225 

4-T414 

5-T425, T400.T426 

8-T800 

9-T801,T805 

a - T400, T414, T425, T800, T801, T805 

b-T400,T414,T425 
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e denotes the execution error mode. The values it can take are: 

h-on execution, an errorwill immediately haft the transputer. 

s - when an error occurs, this process will terminate. 

x - the program can be executed in either HALT or STOP 
mode. 



A.7 Message handling 

All tools in the toolsets display diagnostic messages in a standard format. This has 
certain advantages: 

1 The tool generating the message can be identified even when the tool is 
run out of contact with the terminal. 

2 User programs or system utilities can be used to detect and manipulate 
errors. Some host system editors permit automatic location of errors. 

A.7.1 Message format 

Diagnostic messages are displayed in a standard format by alt tools. The general- 
ized format can be expressed as follows: 

severity - toolname - [ filename [ (Hnenumber } ] ]-message 

where: severity indicates the severity level. Severity categories are described 
beJow. 

toolname is the standard toolset name for the tool. Names used to rename 
tools by the user, are not used. 

filename and Hnenumber indicate the file and line where an error occurred. 
They are only displayed if the error occurs in a file. They are commonly 
displayed when files of the wrong format are specified on the command 
line, for example, a source file is specified where an object file is expected. 

message explains the error and may recommend an action. 

A.7.2 Severities 

The severity attached to the message indicates the importance of the diagnostic 
to the operation of the tool. It also implies a certain action taken by the tool. 

Five severity categories are recognized: 

Information Warning Error Serious Fatal 

Information messages provide the user with information about the functioning or 
performance of the tool. They do not indicate an errorand no useraction is required 
in response. 
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Warning messages identity minor logical inconsistencies In code, or warn of the 
impending generation of more serious errors. The tool continues to run and may 
produce usable output if no serious errors are encountered subsequently 

Error messages indicate errors from which the tool can recover in the short-term 
but may cause further errors to be generated which may lead to termination. The 
tool may continue to run but further errors are likely and the tool is likely to abort 
eventually. No output is produced. 

Serious errors are errors from which no recovery is possible. Further processing 
is abandoned and the tool aborts immediately. No output is produced. 

Fatal errors indicate internal inconsistencies in the software and cause immediate 
termination of the operation with no output. Fatal errors are unlikely to occur but 
if they do the fact should be reported to your local 1NMOS distributor or field 
applications engineer. 

A.7.3 Runtime errors 

Errors which prevent the program from being run are detected by the runtime 
system at startup or during program execution. These errors are displayed in a 
similar format to that used by the tools. All runtime errors are generated at Fatal 
seventy and cause immediate termination of the program. 
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This appendix first identifies the INMOS transputer types supported by this toolset. 
It then explains the concept of transputer classes in terms of developing programs 
for multiple transputer targets. This includes compiling and linking program 
modules. The examples given are based on the ( Hello world' program, written in 
C and compiled with the ice compiler. 

It also explains the command line options which can be used to specify a target 
processor or transputer class. 

Note: the information given in this appendix covers the current range of INMOS 
transputers and language compilers; readers should ignore details of transputer 
types or languages which do not apply to this particular toolset. 



B.1 Transputer types supported by this toolset 

The ANSI C and occam 2 toolsets can be used to develop programs targetted at 
the following INMOS transputer types: 

IMS M212, T212, T222, T225, T400, T414, T425, T426, T800, T801, T805. 

The FORTRAN toolset can only be used to develop programs targetted at 32-bit 
transputers. This includes the following INMOS transputer types: 

IMS T4Q0, T414, T425, T426, T8Q0, T801 , T805. 

The default type assumed by various tools, if none is specified on the command 
line, is T414. 



B.2 Transputer types and classes 

This section describes the meaning of transputer types and classes and how 
selection of the target processor affects the compilation and linking stages of 
program development. The section describes how to compile and link code 
targeted at a single processor type and then describes how to compile and link 
programs so that they can be executed on different processor types. 

B.2.1 Single transputer type 

For those who have a single transputer or indeed a network of transputers all of 
the same type, the compilation and linking stages of program development are 
very straightforward. Simply compile and link all your modules for the required 
processor. 
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Example: to compile and link for a T800: 
ice hello -tSOO 
ilink hello. tco -t800 -f cstartup.lnk (UNIX) 

ice hello /t800 

ilink hello, tco /t800 /f cstartup.lnk {MS-DOS and VMS) 

For a T414 the command lines are simpler 
ice hello 
ilink hello. tco -f cstartup.lnk (UNIX) 

ice hello 

ilink hello .tco /f cstartup.lnk (MS-DOS and VMS) 

B.2.2 Creating a program which can run on a range of transputers 

The compiler and linker use the concept of transputer class to enable programs 
to be developed which may be run on different transputer types without the need 
to recompile. 

A transputer class identifies an instruction set which is common to all the proces- 
sors in that class. When a program is compiled and linked for a transputer class 
it may be run on any member of that class. 

Note: Code created for a transputer class will often be less efficient than code 
created for a specific processor type. Therefore, creating code for a transputer 
class is discouraged in situations where program efficiency is a primary concern; 
it should only be performed where there is a genuine need to produce code which 
will run on a range of transputers or to reduce the size of a support library, where 
program efficiency is not a major concern. 

Table B.1 lists all the transputer classes which the compiler and linker support and 
indicates which processors the program can be run on. 



Transputer class 


Processors which class can be run on 


T2* 


T212,M212,T222,T225 


T3* 


T225 


T4 


T414, T400, T425, T426 


T5 


T400, T425, T426 


T8 


T800, T801,T805 


T9 


T8Q1,T805 


TA 


T400, T414 r T425, T426, T800, T801 r T805 


TB 


T400,T414,T425 J T426 


* Not applicable to the FORTRAN toolset 



Table B.1 Transputer classes and target processor 
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In order to develop a program which will run on different processor types, perform 
the following steps: 

1 Identify the processors on which the program is to run, 

2 Using Table B.1 select the class which may be run on all the target proces- 
sors. 

3 Compile and link all the program modules for this class. 

For example, to create a program which will run on both a T400 and a T425, 
compile and link for transputer class T5: 

ice hello -t5 

ilink hello. tco -t5 -f cstartup. Ink (UNIX) 

ice hello /t5 

ilink hello, tco /t5 /f cstartup. Ink (MS-DOS and VMS) 

Alternatively to create a program which will run on a T40Q, T425 or a T800, compile 
and link for transputer class TA: 

ice hello -ta 

ilink hello. tco -ta -f cstartup. Ink (UNIX) 

ice hello /ta 

ilink hello, tco /ta /£ cstartup. Ink (MS-DOS and VMS) 

Code compiled for a T414 (class T4) may be run on a T400 or T425, which form 
class T5. 

Programs compiled for the T212, M212, or T222 transputers i.e. class T2, can be 
run on a T225 (class T3) because a T225 has a similar but larger instruction set 
than class T2 transputers. Similarly the T400, T425 and T426 have additional 
instructions to those of the T414. Likewise, code compiled for a T800 (class T8) 
mayberunonaT801 or T805, which form classT9. Again the T801 and T805 have 
additional instructions to those of the T800. See section B.2.4. 

B.2.3 Linked file containing code compiled for different targets 

This section describes how object code compiled for one target processor or trans- 
puter class can be linked with code compiled for different transputer types or 
classes. 

The ability to do this provides the user with greater flexibility in the use of program 
modules: 

• An individual module can be compiled once e.g. for class T4, and then 
linked with separate programs to run on different processor types e.g. 
T414andT425. 
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• When the user is preparing a library for use by programs intended to run 
on different processor types, a single copy of code compiled for a trans- 
puter class can be inserted instead of multiple copies for specific trans- 
puters. 

When linking a collection of compiled units together into a single linked unit, the 
user must select a specific transputer type or transputer class on which the linked 
unit is to run. As before, this determines the set of transputer types on which the 
code wilt run. When linking for a particular type or class, the linker will accept 
compilation units compiled for a compatible class. Table B.2 shows which trans- 
puter types and classes the linker will accept when linking for a particular class. 



Link class 


Transputer classes which may be linked 


T2* 


T2 


T3* 


T3,T2 


T4 


T4, TB, TA 


T5 


T5, T4, TB, TA 


T8 


T8 


T9 


T9,T8 


TB 


TB,TA 


TA 


TA 


* Not applicable to the FORTRAN toolset 



Table B.2 Linking transputer classes 

For example, if the target processors are a T400 and a T425 the user may compile 
for classes T5 and TB and link the code for for class T5. Code for a different trans- 
puter class can be included in the final linked unit, as long as: 

• It uses the instruction set or a subset, of the instruction set of the link class 

• The calling conventions are the same. 



Classes T8 and T9 cannot be linked with class TA. This is a change from early 
toolset releases e.g. the Dx11 C toolsets, the Dx05 occam toolsets and the 
Dx13 3L FORTRAN toolsets. 



The reason why these classes cannot be linked together is explained in 
section B.2.4. which gives details of the differences between the instruction sets, 
as additional information. 

A library can be made f consisting of the same modules compiled for different trans- 
puter types or classes. The user then needs only to specify the library file to the 
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linker, and the linker will choose a version of a required routine which is suitable 
for the system being linked. 

The linker uses the rules given in Table B.2 to determine whether a compiled 
module, found in a library, is suitable for linking with the current system. So, for 
example, to create a library which may be linked with any transputer class or 
specific transputer type, all routines could be compiled for classes T2, TA and T8. 

If there are a number of possible versions of a module in a library the best one (i.e. 
the most specific for the system being linked) is chosen. 

occam object files targetted at different targets 

For Occam programs the above rules must also be applied during the program 
design stage when deciding which modules should call each other. Code for a 
different transputer class can be called provided that it uses the instruction set or 
a subset of the instruction set of the calling class. (This is because the compiler 
needs to know which modules to select from libraries containing copies for 
different processor types). 

Table B.2 can be used as guide, by regarding the link class' as the 'calling class 1 
and the transputer classes which may be linked', as the 'transputer classes which 
may be called'. 

Note: classes T8 and T9 cannot call class TA. 

Note: At configuration level, code compiled for class TA can be run on a T8 trans- 
puter, provided it does not include any function which returns an arithmetic REAL. 
This is because of the different methods of evaluating REAL arithmetic for different 
transputer targets, see section B.2A 

B.2.4 Classes/instruction sets - additional information 

The instruction sets of the transputer classes differ in the following ways: 

• Classes T2 and T3 support 16-bit transputers whereas aJI the other trans- 
puter classes support 32-bit transputers. 

• Class T3 is the same as class T2 except that T3 has some extra instruc- 
tions to perform CRC and bit operations, dup, double word indexing and 
includes special debugging functions. 

• Class T5 is the same as class T4 except that T5 has extra instructions to 
perform CRC, 2D block moves, bit operations, double word indexing, 
special debugging functions and also includes the dup instruction. 

• Class T9 is the same as class T8 except T9 has additional debugging 
instructions. 

• The T800, T801 and T805 processors use an on-chip floating point 
processor to perform REAL arithmetic. Thus a large number of floating 
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point instructions are available for these transputers and for their 
associated classes T8 and T9. These instructions are listed in the instruc- 
tion set appendix of the User Guide. 

• For the T414, T400, T425 and T426 processors i.e. transputer classes T4 
and T5 the implementation of REAL arithmetic is in software. These trans- 
puters make use of a small number of floating point support instructions. 
Details can be found in the instruction set appendix of the User Guide. 

• The instruction set of class TA only uses instructions which are common 
totheT400, T414, T425, T426, T800, T801 and T805 transputers. There- 
fore it does not use the floating point instructions, the floating point support 
instructions or the extra instructions to perform CRC, 2D block moves or 
special debugging or bit operations and it does not use the dup instruction. 

• The instruction set of class TB only uses instructions which are common 
to the T400, T414, T425 and T426 processors. Therefore it uses the 
floating point support instructions, but does not use the extra instructions 
to perform CRC, 2D block moves or special debugging or bit operations 
and it does not use the dup instruction. 

When considering the similarities and differences in the instruction sets of different 
transputer classes it helps to divide them into the separate structures as shown 
in Figure B.1. 




Figure B.1 Structures for mixing transputer types and classes 

By comparison with Table B.2 it can beseenthata module may only be linked with 
modules compiled for a transputer class which belongs to the same structure. 

Classes T2 and T3 are targetted at 16-bit transputers so it is obvious that they 
cannot be linked with the other classes which ar all targetted at 32-bit transputers. 
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The reason why classes T8 and T9 cannot be linked with classes TA, TB, T5 or 
T4 is because floating point results from functions are returned in a floating point 
register for T8 and T9 code and in an integer registerfor all other 32-bit processors. 
Even if your code does not perform reaf arithmetic, linking code compiled for a T9 
or T8 with code compiled for any of the other dasses is not permitted. 

To summarize, compiling code for the transputer classes TA and TB enables it to 
be run on a large number of transputer types, however, the code may not be as 
efficient as code compiled for one of the other transputer classes or for a specific 
transputer type. For example compiling code for class T5 enables the CRC and 
2D block move instructions to be used, whereas these instructions are not avail- 
able to code compiled for classes TA and TB. 



B.3 Transputer type command line options 

This section lists the command line options used to specify a target processor or 
transputer class. The options can be used with the following tools: 

ice - The ANSI C compiler, 

oc - The occam 2 compiler. 

if 77 - The FORTRAN-77 compiler, 

ilink - The toolset linker. 



72TDS367 01 March 1993 



308 



B.3 Transputer type command line options 



option 


Description 


TA 


Specifies target transputer class TA (T400, T414 F T425, 




T426,T8G0,T801,T8Q5). 


TB 


Specifies target transputer class TB (T400, T414, T425, 




T426) 


T212 


Specifies a T212 target processor. 


T222 


Specifies a T222 target processor Same as T212 


H212 


Specifies a M212 target processor. Same as T212 


T2 


Same as T212, T222 and M212 


T225 


Specifies a T225 target processor 


T3 


Same as T225. 


T400 


Specifies a T400 target processor. Same as T425. 


T414 


Specifies a T414 target processor. This is the default 




processor type and may be omitted when the target 




processor is a T414 processor. 


T4 


Same as T414 (default). 


T425 


Specifies a T425 target processor 


T426 


Specifies a T426 target processor. 


T5 


Same as T400, T425 and T426. 


T800 


Specifies a T800 target processor. 


T8 


Same as TB00. 


T801 


Specifies a T801 target processor. Same as T805. 


T805 


Specifies a T805 target processor. 


T9 


Same as T801 and T805. 



Table B.3 Transputer type command line options 
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This appendix provides a technical description of the host fife server protocol for 
version 1 .5 of the i server. It also describes the basic set of server functions which 
all versions of iserver must support and includes a set of extensions which may 
be present in some versions of iserver. 

C.1 iserver packets 

Every communication, both to and from the server, is a packet comprising a 
counted array of bytes. The first two bytes are a (little endian) count of the following 
message length. This is followed by a tag byte which specifies the iserver 
command. The remaining bytes are parameters to the command. Results returned 
by the iserver have a result value in place of the tag byte. 

r s1 I s2 | tag ■ parameters | 

L-message of length (s1 + (256 * s2)) bytes— I 

In Occam this protocol is defined as: 

INT16" []BYTE 

In the to-server direction there is a minimum packet length of 8 bytes (i.e. a 
minimum message length of 6 bytes). In both to and from directions there is a 
maximum packet length of 1040 bytes. The packet size must always be an even 
number of bytes. If the number of bytes is an odd a dummy byte must be added 
to the end of the packet and the packet byte count rounded up by one. 

The server code on the host can take advantage of the fact that it will always be 
able to read 8 bytes from the link at the start of a transaction, 

C.2 Server commands 

The functions implemented by the server are separated into five groups: 

• File commands 

• Record Structured file commands 

• Host commands 

• Server commands 

• Reserved and Third Party commands 
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C.2 Server commands 



The following sections contain descriptions of each command under each of the 
five groups. 

In the descriptions the arguments and results of server calls are listed in the order 
that they appear in the data part of the protocol packet. The length of a packet is 
the length of all the items concatenated together, rounded up to an even number 
of bytes, 

Occam types are used to define the format of data Items in the packet All integer 
types are communicated least significant byte first. Negative integers are repre- 
sented in 2s complement. Strings and other variable length blocks are introduced 
by a 16 bit signed count. 

All server calls return a result byte as the first item in the return packet. If the opera- 
tion succeeds the result byte will be zero. If the operation fails the result byte will 
be non-zero. The result will be one (1 ) in the special case where the operation failed 
because it was not implemented. If the result is not zero, some or all of the return 
values may not be present, resulting in a smaller return packet than if the call was 
successful. All server calls will use, where possible, a failure code from Table C.1 
to give details of the failure. 1 



Value 


Name 


Description 





Success 


Success. 


1 


NoCommand 


Command not implemented. 


128 


Reserved 


Unknown error. 


129 


Failed 


Unknown error. 


130 


Reserved 


Never generated. 


131 


IMoPriv 


Insufficient privilege. 


132 


NoResource 


Insufficient system resources available. 


133 


NoFile 


File not found. 


134 


Truncated 


Data truncated. 


135 


Badld 


A bad file id was specified. 


136 


NoPosn 


File position has been lost. 


137 


NotAvailable 


The requested configuration can not be provided. 


138 


EOF 


An end of file mark has been encountered. 


139 


Reserved 


Reserved for use by Linkops. 


140 


Reserved 


Reserved for use by Linkops. 


141 


BadParas 


Invalid or inconsistent parameters. 



Table C.1 iserver failure codes 



1 . Result values between 2 and 127 are defined to have particular meanings by Occam server 
libraries, result values of 1 28 or above are specific to the implementation of a server. 
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C.3 File commands 

Open files are identified with 32 bit descriptors. There are three predefined open 
files: 

standard input 

1 standard output 

2 standard error 



If one of these is closed it may not be reopened. 

If an application is both reading and writing to a file, then no read operation can be 
followed directly with a write operation and vice versa. Fseek must be called 
between a read/write or write/read, otherwise the error code NoPosn will be 
returned. 

When reading from a file open in text mode, the host's newline sequence will be 
translated into the single character LiNEFEED(OxOa). No translation will be 
performed on binary files. 

When writing to a file open in text mode, the single character linefeed (OxGa) 
will be translated into the host's newline sequence. No translation will be performed 
on binary files. 



C.3.1 Fopen - Open a file 

Synopsis : Streamld = Fopen ( Name , Type r Mode ) 

To server: BYTE Tag = 10 

INT16; : []BYTE Name 

BYTE Type = 1 or 2 

BYTE Mode = 1 . . . 6 



From server: 



BYTE 
INT32 



Result 

Streamld 



Fopen opens the file Name and, if successful, returns a stream identifier 
Streamld. 

Type can take one of two possible values: 



Value 


Name 


Description 


1 
2 


Binary 
Text 


The file will contain raw binary bytes. 

The file will be stored as text records. 
Text files are host-specified. 
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Mode can have 6 possible values: 



Value 


Name 


Description 


1 


jnpj'i 


Open an existing file for input 


2 


Output 


Create a new file, or truncate an existing one, for 
output 


3 


Append 


Create a new file, or append to an existing one, for 
output 


4 


ExistingUpdate 


Open an existing file for update (both reading and 
writing), starting at the beginning of the file 


5 


NewUpdate 


Create a new file, or truncate an existing one, for 
update 


6 


Append Update 


Create a new file, or append to an existing one, for 
update 



When a file is opened for update (one of the last three modes above) then the 
resulting stream may be used for input or output There are restrictions however 
an output operation may not follow an input operation without an intervening 
Fseek, Ftell or Ff lush operation. 

The number of streams that may be open at one time is host-specified, but will not 
be less than eight (including the three predefines), 



Return Codes 

Success Failed 



NoPriv 



NoResource 



NoFile 



C.3.2 Fclose - Close a file 



Synopsis : Fclose ( Streamld ) 
To server: 



BYTE 
INT32 



From server: BYTE 



Tag = 11 
Streamld 

Result 



Fclose closes a stream streamld which should be open for input or output. 
Fclose flushes any unwritten data and discards any unread buffered input before 
closing the stream. 



Return Codes 

Success Failed 



Badld 



NoResource 
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C.3.3 Fread - Read a block of data 

Synopsis: Data = Fread ( Streamld,. Count ) 

To server: BYTE Tag = 12 

INT32 Streamld 

INT 16 Count 

From server: BYTE Result 

INT16: : []BYTE Data 

This function should not be used. It has been included only for compatibility 
purposes. A replacement routine, FGetBlock, has been provided, which is 
described in C.3.5. 

Fread reads Count bytes of binary data from the specified stream. Input stops 
when the specified number of bytes are read, or the end of file is reached! or an 
error occurs. If Count is less than one then no input is done. The stream is left posi- 
tioned immediately after the data read. If an error occurs the stream position is 
undefined. 

Result is always zero. The actual number of bytes returned may be less than 
requested and Feof and FerrStat should be used to check for status. 

Return Codes 

Success 

C.3.4 Fwrite - Write a block of data 

Synopsis: Written = Fwrite ( Streamld, Data ) 

To server: BYTE Tag =13 

INT32 Streamld 

INT16: : []BYTE Data 

From server: BYTE Result 

INTlfi Written 



This function should not be used. It has been included only for compatibility 
purposes. A replacement routine, FPutBlock, has been provided, which is 
described in C.3.6. 

Fwrite writes a given number of bytes of binary data to the specified stream, which 
should be open for output. If the length of Data is less than zero then no output is 
done. The position of the stream is advanced by the number of bytes actually 
written. If an error occurs then the resulting position is undefined. 
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Fwrite returns the number of bytes actually output in Written. Result is always 
zero. The actual number of bytes returned may be less than requested and Feof 
and FerrStat should be used to check for status. 

If the Streamld is 1 (standard output) then the write is automatically flushed. 

Return Codes 

Success 

C.3.5 FGetBlock - Read a block of data and return success 

Synopsis: Data = FGetBlock { Streamld, Count ) 

To server: BYTE Tag = 23 

INT32 Streamld 

INT16 Count 

From server: BYTE Result 

INT16:: []BYTE Data 



FGetBlock reads Count bytes of binary data from the specified stream. Input 
stops when the specified number of bytes are read, or the end of file is reached, 
or an error occurs. If Count is less than one then no input is done. The stream is 
left positioned immediately after the data read. If an error occurs the stream posi- 
tion is undefined. 

The actual number of bytes returned may be less than requested. This is consid- 
ered a failure. Result will contain to indicate success, anything else failure, in 
which case Feof and FerrStat should be used to check for status. 

This function is preferred over the Fread function which should no longer be used. 

Return Codes 

Success Failed Truncated Bad Id 
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C.3.6 FPutBlock - Write a block of data and return success 

Synopsis: Written = FPutBlock { Streamld, Data J 

To server: BYTE Tag = 24 

INT32 Streamld 

INT16:: []BYTE Data 

From server: BYTE Result 

INT16 Written 



FPutBlock writes a given number of bytes of binary data to the specified stream, 
which should be open for output. If the length of Data is less than or equal to zero 
then no output is done. The position of the stream is advanced by the number of 
bytes actually written. If an error occurs then the resulting position rf undefined. 

FPutBlock returns the number of bytes actually output in Written. The actual 
number of bytes returned may be less than requested. Result will contain to 
indicate success, anything else failure, in which case Feof and FerrStat should be 
used to check for status. 

If the Streamld is 1 (standard output) then the write is automatically flushed. 

This function is preferred over the Fwrite function which should no longer be used. 

Return Codes 

Success Failed NoResource Badld NoPosn 

C.3.7 Fgets - Read a line 



Synopsis: 


Data a 


Fgets ( 


Streamld, 


To server: 


BYTE 




Tag = 14 




INT32 




Streamld 




INT16 




Count 


From server: 


BYTE 




Result 




IKT16: 


: []BYTE 


Data 



Fgets reads a line from a stream which must be open for input. Characters are read 
until end of file is reached, a newline is seen or the number of characters read is 
equal to Count. 

If the input is terminated because a newline is seen then the newline sequence is 
not included in the returned array. 
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If end affile is encountered and nothing has been read from the stream then Fgets 
fails. 

Return Codes 

Success Failed Badld NoPosn 

C.3.8 Fputs - Write a line 

Synopsis: Fputs ( Streamld, String ) 

To server: BYTE Tag = IB 

INT32 Streamld 

INT16: : []BYTE String 

From server: BYTE Result 



Fputs writes a line of text to a stream which must be open for output. The host-spe- 
cified convention for newline will be appended to the line and output to the file. The 
maximum line length is host-specified. 

Return Codes 

Success Failed NoResource Badld NoPosn 

C.3.9 Fflush - Flush a stream 

Synopsis: Fflush ( Streamld ) 

To server: BYTE Tag = 16 

IKT32 Streamld 

From server: BYTE Result 



Fflush flushes the specified stream, which should be open for output. Any inter- 
nally buffered data is written to the destination device. The stream remains open. 

Return Codes 

Success Failed NoResource Badld 
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C.4 Record Structured file commands 

This section describes the commands for record structured files. File formats are 
discussed in Section C.8. 



C .4.1 FopenRec - Open a record structured file 

Synopsis: Streamld, RealMrs = FopenRec ( Name, Type, Mode, 
Mrs ) 



To server: 


BYTE 




Tag = 26 




IKT16: 


: []BYTE 


Name 




BYTE 




Organisation = 3 




BYTE 




Mode = 1 . , . 6 




BYTE 




Type = . . . 2 




BYTE 




Format = ... 1 




IKT32 




Mrs 


From server: 


BYTE 




Result 




INT32 




RealMrs 




INT32 




Streamld 




BYTE 




Real Type 



FopenRec opens the file Name and, if successful, returns a stream identifier 
Streamld. 

Organisation can take one of two possible values: 



Value 


Name 


Description 


3 

4 


Variable 
Fixed 


The file will be organized in records of variable length. 
The maximum record size is contained in the Mrs field. 

The file will be organized in records of fixed length. The 
size of a record is supplied in the Mrs field. Record 
files are implemented in a host-specific way. 



For each organization, Type can have one of the following values: 



Value 


Name 


Description 




1 
2 


DontCare 

Stream 
Record 


Use whatever type is most natural, and return the type 
in Real Type. 

Use streams. 

Use record oriented files. 
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Format can take one of two possible values: 



Value 


Name 


Description 



1 


Formatted 
Unformatted 


Formatted record structured file 
Unformatted record structured file 



Mode can have 6 possible values: 



Value 


Name 


Description 


1 
2 

3 

4 

5 

6 


Input 
Output 

Append 

ExistingUpdate 

NewUpdate 

AppendUpdate 


Open an existing file for input 

Create a new file, or truncate an existing one, for 
output 

Create a new file, or append to an existing one, for 
output 

Open an existing file for update (both reading and 
writing), starting at the beginning of the file 

Create a new file, or truncate an existing one, for 
update 

Create a new file, or append to an existing one, for 
update 



When a file is opened for update (one of the last three modes above) then the 
resulting stream may be used for input or output. There are restrictions however; 
an output operation may not follow an input operation without an intervening 
Fseek, Ftell or Ff lush operation. 

When an existing file is opened, the record size supplied in the open request is 
compared with that stored in the file if possible (some hosts do not record this 
information). If they are different then the open fails. If the real record size is not 
available, it is considered to be the same as the requested record size, and so the 
open can succeed. The actual record size for the file is returned in ReaiMrs. 

The number of streams that may be open at one time is host-specified, but will not 
be less than eight (including the three predefines). 

Return Codes 



Success Failed 
NotAvailable 



NoPriv 



NoResource 



NoFile 
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C.4.2 FGetRec - Read a record 

Synopsis: Data = FGetRec ( StreamXd ) 

To server: BYTE Tag = 27 

INT32 Streamld 

INT16 ChunkSize 

INT32 Offset 

BYTE PerformRead 

From server: BYTE Result 

INT32 RecordSize 

INT16: : []BYTE Data 

FGetRec reads a record from a record stream which must be open for input. 

If an end of file record is encountered then FGetRec fails. If PerformReadis non- 
zero, then a record is transferred from the file specified by Streamld into the serv- 
er's buffer, otherwise, data from the previous FGetRec is transferred. If Per form- 
Read is zerOj and no records have ever been read from Streamld, then FGetRec 
fails, ChunkSize specifies the number of bytes to be transferred, starting at byte 
number offset from the record buffer. 

Return Codes 

Success Failed Badld NoPosn EOF 

C A3 FPutRec - Write a record 



Synopsis : 


FPutRec 


( Strea 


aid, Record ) 


To server: 


BYTE 




Tag = 28 




INT 3 2 




Streamld 




INT 3 2 




RecordSize 




INT16 




ChunkSize 




INT 3 2 




Offset 




BYTE 




PerformWrite 




INT16*. : 


[J BYTE 


Record 


From server ; 


BYTE 




Result 



FPutRec writes a record to a record stream which must be open for output. 
ChunkSize specifies the number of bytes to be transferred, starting at byte 
numberOff set into the record buffer. RecordSize specifies the size of the entire 
record. If Perf ormWri te is non-zero, then a record is transferred to the file speci- 
fied by Streamld from the server's buffer, otherwise, data from a previous record 
is transferred. 
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Return Codes 

Success Failed 



Bad Id 



NoPosn 



C.4.4 FputEOF - Write an end of file record 



Synopsis : 
To server: 



FputEOF( Streamld ) 



BYTE 
INT32 



From server: BYTE 



Tag = 29 
Streamld 

Result 



FPutEOF writes an end of file record to a record structured file. When the file is 
closed, the file will be truncated after the first end-of-fite record and data after it will 
be lost. 



Return Codes 

Success Failed 



Bad Id 



C.4.5 Fseek - Set position in a file 



Synopsis : 
To server: 



Fseek ( Streamld, Offset, Origin } 



BYTE 
INT32 
INT32 
INT32 



From server: BYTE 



Tag = 17 
Streamld 
Offset 
Origin 

Result 



Fseek sets the file position for the specified stream. A subsequent read or write 
will access data at the new position. 

For a binary file the new position will be Offset characters from Origin which 
may take one of three values: 



Value 


Name 


Description 


1 
2 
3 


Set 

Current 

End 


The beginning of the file. 
The current position in the file. 
The end of the file. 



Fora text stream, Offset must be zero or a value returned by Ftell. If the latter 
is used then Origin must be set to 1 . For a record structured file Offset is the 
number of records to seek from Origin. 
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Return Codes 

Success Failed Badld 

C.4.6 Ftell - Find out position in a file 

Synopsis: Position = Ftell ( Streamld ) 

To server: BYTE Tag = 18 

INT32 Streamld 

From server: BYTE Result 

INT32 Position 

Ftell returns the current file position for streamld. For record structured files, the 
Position is the record number relative to the start of the file. 

Return Codes 

Success Failed BadJd 

C.4.7 Feof - Test for end of file 



Synopsis : 


Feof ( Streamld } 


To server: 


BYTE Tag = 19 




INT32 Streamld 



From server: BYTE Result 

Feof succeeds if the end of file indicator for streamld is set. Note that the defini- 
tion of 'end of fife' is any attempt to read past the last byte in the file, i.e, Reading 
the last byte in a file will not set EOF; attempting to read the next byte will 

Return Codes 

Success Failed Badld 
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0.4,8 Ferror - Get file error status 

Synopsis: ErrorNo, Message = Ferror (Streamld) 

To server: BYTE Tag = 20 

INT32 Streamld 

From server: BYTE Result 

INT32 ErrorNo 

INT16: : []BYTE Message 

This function should not be used. It has been included only for compatibility 
purposes. A replacement routine, FGetBlock, has been provided, which is 
described inC.3.5. 

Ferror succeeds if the error indicator for streamld is set. If it is, Ferror returns 
a host-defined error number and a (possibly null) message corresponding to the 
last file error on the specified stream. The maximum size of Message will be 
restricted to 506 bytes for compatibility purposes. If the message is longer, then 
it will be truncated to fit and Ferror will fail. 

Return Codes 

Success Failed 

C.4.9 Remove - Delete a file 



Synopsis: Remove ( Name ) 

To server: BYTE Tag = 21 

INT16: : []BYTE Name 

From server: BYTE Result 



Remove deletes the named file. 
Return Codes 

Success Failed NoPriv NoFile 
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C.4.10 Rename - Rename a file 

Synopsis: Rename ( OldName, NewName } 

To server: BYTE Tag = 22 

INT16 : : [ ] BYTE OldName 
INT16 : : [ ] BYTE NewName 

From server: BYTE Result 

Rename changes the name of an existing file OldName to NewName, 
Return Codes 

Success Failed NoPriv NoFile 

CA11 Isatty - Discover if a stream is connected to a terminal 

Synopsis: Isatty { Streamld ) 

To server: BYTE Tag = 25 

INT32 Streamld 

From server: BYTE Result 

BYTE Istty 

Isatty determines ifthe stream specified by Streamld is connected to a terminal. 
Any non-zero value in I satty indicates that the stream is connected to a terminal. 

Return Codes 

Success Failed Badld 
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C.4.12 FileExists - Check to see if a file exists 

Synopsis: Exists : = FileExists ( Name ) 

To server: BYTE Tag = 80 

INT16: ; [JBYTE Name 

From server: BYTE Result 

BYTE Exists 

FileExists checks to see if the file Name exists. Any non-zero value in Exists indi- 
cates that the file does exist 

Return Codes 

Success Failed 

C.4.13 FerrStat - Get file error status 

Synopsis: ErrorNo, Message = FerrStat { Streamld ) 

To server: BYTE Tag = 82 

INT32 Streamld 

INT16 MessLen 

From server: BYTE Result 

INT32 ErrorNo 

INT1 6 : : [ ] BYTE Message 

FerrStat succeeds iftheerrorindicatorforStreamldisset.lfitis, FerrStat returns 
a host-defined error number and a (possibly null) message corresponding to the 
last file error on the specified stream. The maximum size of Message is restricted 
to MessLen bytes. If the message is longer, then it will be truncated to fit and Ferr- 
Stat will fail with status of Truncated. 

Return Codes 

Success Failed Truncated 
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C.5 Host commands 
C.5.1 Getkey - Get a keystroke 



Synopsis : 


Key = 


GetKey () 




To server: 


BYTE 




Tag = 30 


From server: 


BYTE 




Result 




BYTE 




Key 



GetKey gets a single character from the keyboard. The keystroke is waited on 
indefinitely and will not be echoed. The effect on any buffered data in the standard 
input stream is host-defined. It should be noted that GetKey will only get one char- 
acter from the keyboard stream; if a single key-press results in more than one char- 
acter being generated, then GetKey/Pollkey should be called as many times as 
required to read them all. 

Return Codes 

Success Failed 



C.5.2 Pollkey - Test for a key 



Synopsis : 


Key = 


PollKeyO 




To server : 


BYTE 




Tag = 31 


From server: 


BYTE 




Result 




BYTE 




Key 



PolIKey gets a single character from the keyboard. If a keystroke is not available 
then PolIKey returns immediately with a non-zero result. If a keystroke is available 
it will not be echoed. The effect on any buffered data in the standard input stream 
is host-defined. It should be noted that PolIKey will only get one characterfrom the 
keyboard stream; if a single key-press results in more than one character being 
generated, then GetKey/PollKey shouEd be called as many times as required to 
read them aJL 

Return Codes 

Success Failed 
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C.5.3 RequestKey - Request a single keyboard 'event 1 

Synopsis: Result = RequestKey () 

To server: BYTE Tag =36 

From server: BYTE Result 

This command should never be generated by an application. It may be used 
by the linXops server to improve performance over a network. 

Once iserver has received one of these requests, it monitors the keyboard and if 
a key is pressed, it generates a keyboard 'event 1 across the Link. This event will 
never reach the application since it will have been filtered out by the linkops 
server. Each RequestKey command will only solicit one keyboard event The 
'event* that iserver generates looks exactly like the reply to the GetKey command. 
It will only be generated while iserver is idle (waiting for another iserver request to 
arrive). 

Return Codes 

Success & Failed 

C.5.4 Getenv - Get environment variable 

Synopsis: Value = Getenv ( Name ) 

To server: BYTE Tag = 32 

INT16:: []BYTE Name 

From server: BYTE Result 

INT16: : []BYTE Value 



This function should not be used. It has been included only for compatibility 
purposes. A replacement routine, Translate, has been provided, which is 
described in C.5.7. 

Getenv returns a host-defined environment string for Name. If Name is undefined 
then Result will be non-zero. If the resultant environment string for Name is longer 
than 509 bytes, then it will be truncated to fit and Getenv will fail. 

Return Codes 

Success Failed 
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C.5.5 Time - Get the time of day 

Synopsis: LocalTime, UTCTime = Time() 

To server: BYTE Tag = 33 

From server: BYTE Result 

UNSIGNED INT32 LocalTime 
UNSIGNED INT32 UTCTime 

Time returns the local time and Coordinated Universal Time if it is available. Both 
times are expressed as the number of seconds that have elapsed since midnight 
on 1st January, 1970. If UTCtime is unavailable then it will have a value of zero. 

Return Codes 

Success Failed 

C.5.6 System - Run a command 

Synopsis: Status = System ( Command ) 

To server: BYTE Tag = 34 

INT1 6 : : [ ] BYTE Command 

From server: BYTE Result 

INT32 Status 



System provides access to the host's command processor, if one is available. If 
the length of Command is zero, then the command processor will not be invoked 
(and the empty string therefore not executed), and System will succeed only if a 
command processor is available. The value of status is undefined in this case. 
If the length of Command is non-zero, then the string is passed to the command 
processor, which will attempt to execute it In this case Status is the return value 
of the command, which is host-defined. 

Return Codes 

Success Failed NoResource 
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C.5.7 Translate - Translate an environment variable 



Synopsis: Value = Translate { Name, Length ) 

To server; BYTE Tag = 81 

INT32 Offset 

INT16 Length 

INT16: : []BYTE Name 

From server: BYTE Result 

INT32 TotalLength 

IKT16: : []BYTE Value 



Translate returns a host-defined environment string for Name. If Name is undefined 
then Result will be non-zero. Data is transferred from the resultant string starting 
at Offset for Length bytes, if Offset is beyond the end of the string, then an 
empty (zero length) string will be returned. The TotalLength field of the reply 
contains the total length of the translated string. 

Return Codes 

Success Failed 
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C.6 Server commands 
C.6.1 Exit -Terminate the server 



Synopsis : 


Exit( Status ) 


To server: 


BYTE Tag = 35 




INT32 Status 



From server: BYTE Result 

Exit terminates the server, which exits returning Status to its caller. 

If Status has the special value 999999999 then the server will terminate with a 
host-specific 'success' result. 

If Status has the special value -999999999 then the server will terminate with a 
host-specific 'failure 3 result. 

Return Codes 

Success 



C.6,2 Command Line - Retrieve the server command line 



Synopsis: String = CommandLine ( All ) 

To server: BYTE Tag =40 

BYTE All 

From server: BYTE Result 

INT16:: []BYTE String 

This function should not be used. It has been included only for compatibility 
purposes. A replacement routine, CommandArgs, has been provided, which is 
described in C.6.6. 

CommandLine obtains the command line passed to the server. The server is 
passed the command line arguments as a number of discrete items. The items are 
built into a command string using the following rules. 

* The individual items are concatenated together into a string, with a single 
space (0x20) being inserted between each item. 

• Any quote character (0x22) found in any item is quoted, e.g. " becomes "". 

■ Any command line item found to contain whitespace (0x20 or 0x09) has a 
quote character prefixed to it and another added after it. 
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CommandLine returns the command line passed to the server on invocation. On 
certain operating systems it is possible to quote arguments on the command line. 
The quotes themselves have been removed by the time iserver gets to see the 
arguments. When building the command line to pass on to the application, 
iserver places quotes (0x22) around any argument containing whitespace. Any 
genuine quote characters in the command line are quoted, e.g. " becomes "". 

If All is zero the returned string is the command line, with the server name, argu- 
ments that the server recognized (including any parameters to the arguments) 
removed. 

If All is non-zero then the string returned is the entire command vector as passed 
to the server on startup, including the name of the server command itself. 

Return Codes 

Success Failed 



C.6.3 Core - Read peeked memory 

Synopsis Data = Core( Offset, Length ) 

To server: BYTE Tag = 41 

INT32 Offset 

INT16 Length 

From server: BYTE Result 

INT16: : []BYTE Core 



Core returns the contents of the root transputer's memory, as peeked from the 
transputer when the server was invoked with the analyze option. 

Core fails if Offset is larger than the amount of memory peeked from the trans- 
puter or if the transputer was not analyzed. 

If (Offset + Length) is larger than the total amount of memory that was peeked 
then as many bytes as are available from the given offset are returned. 

If Offset and Length are both zero, the the result of this function will indicate if 
the transputer was analyzed and peeked by the server 

Return Codes 

Success Failed 
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C.6.4 Version - Find out about the server 



Synopsis - 


Id = 


Vers 


ion 







To server: 


BYTE 








Tag = 4 


From server: 


BYTE 
BYTE 
BYTE 
BYTE 
BYTE 








Result 

Version 

Host 

OS 
Board 



Use of this function is discouraged. To obtain similar information in a more portable 
manner, use the function Getlnfo (C.6.5). 

Version returns four bytes containing identification information about the server 
and the host it is running on. 

If any of the bytes has the value then that information is not available. 

Version identifies the server version. The byte value should be divided by ten to 
yield a version number 

Host identifies the host box. Currently 8 are defined: 



Value 


Host 


Value 


Host 


1 


PC 


2 


NEC-PC 


3 


VAX 


4 


Sun 3 


5 


IBM 370 


6 


Sun 4 


7 


Sun 386/ 


8 


Apollo 


9 


Atari 







OS identifies the host environment. Currently 5 are defined: 



Value 


Operating system 


Value 


Operating system 


1 
3 
5 


DOS 
VMS 
CMS 


2 
4 
6 


Helios 

SunOS 

TOS 
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Board Identifies the interface board. Currently 12 are defined: 



Value 


Board 


Value 


Board 


1 


IMS B004 


2 


IMS BOOS 


3 


IMS B010 


4 


IMS B011 


5 


IMS B014 


6 


DRX-11 


7 


Caplin QTO 


8 


IMS B015 


9 


IBM CAT 


10 


IMS B016 


11 


UDP 


12 


TCPIink 


13 


ACSILA 







INMOS reserves numbers up to and including 127 for these three fields. 
Return Codes 
Success Failed 

C.6.5 Getlnfo - Obtain information about the host and server 



Synopsis : 

To server: 

From server: 



NoOfBytes = Getlnfo ( Item, Buffer ) 



BYTE 
BYTE 
INT16 



Tag = 43 

Item 

ReplySize 



BYTE Result 

Item specific result 



Getlnfo is used to obtain host and server specific information in as portable a 
fashion as possible. ReplySize specifies the maximum size of the reply in bytes, 
if the reply exceeds this value, it will be truncated and an appropriate failure status 
will be returned. Values for item and their representation are shown in Table C.2, 



Value 


Name 


Returned as 


Description 


1 


SwitchChar 


BYTE 


The switch character used by the 
host 


2 


EndOflJne 


INT16:: []BYTE 


The end of line sequence. 


3 


Stderr 


BOOL 


A boolean value indicating whether or 
not the standard error stream can be 
redirected. 


4 


Serverld 


INT16:*. []BYTE 


A string identifying the server. 


5 


ServerMaj 


INT32 


The server's major version number. 


6 


ServerMin 


INT32 


The server's minor version number. 


7 


PacketSize 


INT32 


The server's maximum packet size. 



Table C.2 Results of Getlnfo command 
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A bool will be represented as a single byte, with any non-zero value meaning 
true, and zero FALSE. 



Return Codes 

Success Failure 



NoPriv 



Truncated 



C.6.6 CommandArgs - Retrieve the server command line arguments 



Synopsis : 
To server; 

From server: 



String ~ CommandArgs ( Argno, Length ) 



BYTE 

INT16 

INT16 

BYTE 
INT16 
BYTE 
INT16: 



[]BYTE 



Tag = 83 

Argno 
Length 

Result 
NumArgs 
Server Arg 
String 



CommandArgs provides access to the server's command line. Argno specifies 
the command line argument number and is used as an index into the server's argv 
array. Length specifies the maximum length of String. If String is too big, it 
will be truncated to fit, and a status of Truncated will be returned, if ServerArg 
is non-zero, it indicates that string was recognized as a server argument, and 
should be ignored by the application. NumArgs is the highest argument number 
which may be requested, and is the equivalent of the C variable argc. Argument 
number zero is always present. 



Return Codes 



Success 



Failed 



Truncated 
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C.7 Reserved Tags and Third Party Tags 

The following tags have been reserved for specific applications or by Third Parties 
for use in their own servers. Their use is not encouraged , since the third party tags 
will not be present in the standard INMOS server. 

C.7.1 MSDOS - Perform MS-DOS specific function 

Synopsis : MsDos (Command) 

To server: BYTE Tag = 50 

BYTE Function code 

Function specific data 

From server: BYTE Result 

Function specific results. 

MSDOS is used to perform a number of MS-DOS specific functions. This is used 
to support some early INMOS PC-based programs. Use of this function is discour- 
aged for portability reasons. The functions supported are shown in Table C.3. 



Value 


Name 


Description 





SendBlock 


Write a block of data anywhere in the PC's memory map. 


1 


GetBlock 


Read a block of data from anywhere in the PC's memory 
map. 


2 


Calllnt 


Invoke a software interrupt. 


3 


GetRegs 


Read the segment registers. 


4 


PortWrite 


Write to a port. 


5 


PortRead 


Read from a port. 



Table C.3 MS-DOS functions 



Return Codes 

Success Failed 
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C.7.2 SocketA - make a socket library call 



Synopsis: BYTE Tag = 70 

BYTE Socket operation 

Function specific data. 

From server: BYTE Result 

Function specific results. 



This function allows an application to make a socket library call. 
Return Codes 
Success Failed 



C.7.3 SocketM - make a socket library call 



Synopsis: BYTE Tag = 71 

BYTE Socket operation 

Function specific data. 

From server: BYTE Result 

Function specific results. 



This function allows an application to make a socket library call. 
Return Codes 
Success Failed 

C.7.4 ALSYS - Perform Alsys specific function 

Synopsis : AlSys (...) 

To server: BYTE Tag = 100 

Function specific data 

From server: BYTE Result 

Function specific results 

Alsys is used to perform a number of Alsys specific functions. This is used to 
support the Alsys compilers. 
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C.7.5 KPAR - Perform Kpar specific function 

Synopsis ; Kpar ( . . . ) 

To server: BYTE Tag =101 

Function specific data 

From server: BYTE Result 

Function specific results 

This is used to perform a number of Kpar specific functions. This is used to support 
Kpar tools. 



C.8 Record Structured file format 

Under VAX/VMS, record structured files are implemented using the VAX Record 
Management Service (VAX/RMS). Under all other hosts record structured files are 
implemented using binary files. Files created are of a similar format to that used 
by Sun FORTRAN. 



C.8.1 SunOS and MS-DOS 

Formatted Sequential 

Each record in a Formatted Sequential file has a linefeed character (0x0a) 
appended to it. Thus an extra byte per record is required, i.e. 



record data 



linefeed 



Unformatted Sequential 

Unformatted Sequential files are implemented by prefixing and suffixing each 
record with a four byte length field, most significant byte first. The length field is the 
length of the data, not the data plus the length fields. This means an extra eight 
bytes per record are required, i.e. 



data length length bytes of data data length 



Formatted Direct 

The record size is specified at open. 

Unformatted Direct 

The record size is specified at open. 
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C.9 Termination codes 

There are various circumstances under which iserver can terminate, iserver 
1.5 makes it possible for a controlling script to distinguish between the following 
cases 

• Terminated properly on receipt of an sps . success token. 

• Terminated properly on receipt of an sps . failure token. 

• Terminated properly with any other value. 

• Terminated on receipt of a user break. 

• Terminated on seeing the transputer error flag set. 

• Any other termination. 

The values used are shown in Table C.4. 



Host 


Termination 


User Break 


Error 
Flag 


Any 
Other 


Success 


Failure 


Other 


MS-DOS 





255 


exit code 


254 


253 


252 


Helios 


I 


255 


exit code 


254 


253 


252 


VAX/VMS 
error class 


1 
success 


4 
fatal 


exilcode x 16 
warning 


10 
information 


2 
error 


12 
fatal 


SunOS 





255 


exit code 


254 


253 


252 



Table C.4 iserver termination codes 

The values chosen for VAX/VMS have been designed to generate different 
'classes' of error. 

Under all operating systems apart from VAX/VMS, error codes between 240 and 
255 are reserved for use by iserver. 
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This appendix describes the format of ]TERM files; it is included for people who 
need to write their own ITERM because they are using terminals that are not 
supported by the standard ITERM file supplied with the toolset. 

Standard ITERM files for this release are provided in the i terms directory, which 
is a subdirectory of the main toolset installation directory. These files may be used 
as templates and tailored to suit your own needs. It is recommended that the instal- 
lation files are not changed in any way, and that modifications are only made to 
copies of the files. 



D.1 Introduction 

ITERMs are ASCII text files that describe the control sequences required to drive 
terminals. Screen oriented applications that use ITERM files are terminal indepen- 
dent. 

ITERM files are similar in function to the UNIX termcap database and describe 
input from, as well as output to, the terminal. They allow applications that use func- 
tion keys to be terminal independent and configurable. 

Within the toolset, the ITERM file is only used by the debugger tool idebug and 
the T425 simulatortool isim. 

Adefault ITERM file maybe defined in the iterm environment variable. For details 
see section D.8 and the Delivery Manual for the release. 



D.2 The structure of an ITERM file 

An ITERM file consists of three sections. These are the host, screen and keyboard 
sections. Sections are introduced by a line beginning with the section letters 'H\ 
'S' or 'K\ Case is unimportant and the rest of the line is ignored. Sections consist 
of a number of lines beginning with a digit. A section is terminated by a line begin- 
ning with the letter 'E'. The host section must appear first; other sections may 
appear in any order in the file. Sections must be separated by at least one bEank 
line. 

The syntax of the lines that make up the body of a section is best described in an 
example: 

3 : 34 , 56 , 23 , 7 . comments 

Each line starts with the index number followed by a colon and a list of numbers 
separated by commas. Each line is terminated by a full stop ('.*) and anything 
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following it is treated as a comment. Spaces are not allowed in the data string and 
an entry cannot be split across more than one line. 

Comment lines, beginning with the character '#', may be placed anywhere in an 
ITERM file. Extra blank lines in the file are ignored. 

The index numbers in each section correspond to an agreed meaning for the data. 
In the following sections the meaning of the data in each of the three sections is 
described in detail. 



D.3 The host definitions 



0.3.1 ITERM version 

This item identifies an ITERM file by version. It provides some protection against 
incompatible future upgrades. 

e.g. 1:2. 

D.3.2 Screen size 

This item allows applications to find out the size of the terminal at startup time. The 
data items are the number of columns and rows, in that order, available on the 
current terminal. 

e.g. 2:80,25. 

Screen locations should be numbered from 0, by the application. Terminals 
which use addressing from 1 , 1 can be compensated for in the definition of goto 
X,Y. 



D.4 The screen definitions 

The lists of values in the screen section represent control codes that perform 
certain operations; the data values are ASCII codes to send to the display device. 

ITERM version 2 defines the indices given in table D. 1 .. These definitions are used 
in the example ITERM file; for a complete listing of the file see section D.8, 
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Index 


Screen operation 


1 


cursor up 


2 


cursor down 


3 


cursor left 


4 


cursor right 


5 


goto x y 


6 


insert character 


7 


delete character at cursor 


8 


clear to end of line 



Index 


Screen operation 


9 


clear to end of screen 


10 


insert line 


11 


delete line 


12 


ring bell 


13 


home and clear screen 


20 


enhance on (not used) 


21 


enhance off (not used) 



Table D.1 ITERM screen operations 

For example, an entry like: '8 : 27 , 91 , 75 . ' indicates that an application should 
output the ASCI I sequence ( ESC [ K J to the terminal output stream to clearto end 
of line. 



D.4.1 Goto X Y processing 

The entry for 5, 'goto X Y', requires further interpretation by the application. A 
typical entry for 'goto X Y' might be: 

5:27,-11,32,-21,32 
The negative numbers relate to the arguments required for X and Y. 

... , -ab f nn r ... 
where: a is the argument number (i.e. 1 for X, 2 for Y). 

b controls the data output format. 

If b =1 output is an ASCII byte (e.g. 33 is output as ! ). 

If b =2 output is an ASCII number (e.g. 33 is output as 33). 

nn is added to the argument before output. 
As a complete example, consider the following ITERM entry in the screen section: 

5:27,91,-22,1,59,-12,1,72. ansi cursor control 

This would instruct an application wishing to move the terminal cursor to X=14 i Y=8 
(relative to 0,0) to output the following bytes to the screen: 

Bytes in decimal: 27 91 57 59 49 53 72 
Bytes in ASCII: ESC [ 9 ; 1 5 H 
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D.5 The keyboard definitions 

Each index represents a single keyboard operation. The data specified after each 
index defines the keystroke associated with that operation. Multiple entries for the 
same index indicate alternative keystrokes for the operation. 

ITERM version 2 defines the indices given in table D.2. These definitions are used 
in the example ITERM file; for a complete listing of the file see section D.8. 



Index 


Function 


2 


delete character 


6 


cursor up 


7 


cursor down 


3 


cursor left 


9 


cursor right 


12 


delete line 


14 


start of line 


15 


end of line 


18 


fine up 


19 


line down 


20 


page up 


21 


page down 


26 


enter file 


27 


exit file 


28 


refresh 


29 


change file 


31 


finish 


34 


help 


36 


get address 



Index 


Function 


39 


goto line 


40 


backtrace 


41 


inspect 


42 


channel 


43 


top 


44 


retrace 


45 


relocate 


46 


info 


47 


modify 


48 


resume 


49 


monitor 


50 


word left 


51 


word right 


55 


top of file 


56 


end of fife 


62 


toggle hex 


65 


continue from 


66 


toggle breakpoint 


67 


search 



Table D.2 fTERM key operations 



D.6 Setting up the ITERM environment variable 

To use an ITERM the application has to find and read the file. An environment vari- 
able (or logical name on VMS) called ITERM should be set up with the pathname 
of the file as its value. 

For more details about setting environment variables see the Delivery Manual that 
accompanies the release. 
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D.7 Iterms supplied with a toolset 

The following ITERM files are supplied with the toolset: 



File 


Description 


ansi.itm 


Generic ANSI iterm 


ncd.itm 


NCD X terminal iterm 


necansi . itm 


NEC PC iterm 


pcansi , itm 


PC iterm (requires ANSI.SYS) 


sun. itm 


SunView iterm 


vtlOO.itm 


vt 100 iterm 



Table D.3 ITERM files supplied 

ansi . itm is likely to be the most portable in that it will work unchanged with most 
hosts. However, because of this it may only use the normal (alpha-numeric keys) 
of a keyboard. This means that some keys (when used in conjunction with the 
CNTL or SHIFT key) are associated with more than one operation. Specific host 
iterms make use of known function keys etc. which leads to less overloading of 
keys. 

Each iterm file may be treated as an example; you may create and use your own 
iterm file if you wish. 
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D.8 An example [TERM 

This is the generic toolset ITERM file for an ANSI terminal. 



ANSI ITERM for any ANSI terminal 
Support for idebug and isim 

VI. 16 November 1990 (RD) 

VI. 1 11 January 1991 (NH) 



Created 

Modified 



host section 

1:2. 

2:80,24. 

end of host section 

# screen control characters 

screen section 

# 

1:27,91,65. 

2:27,91,66. 

3:27,91,68. 

4:27,91,67. 

5:27,91,-22,1,59,-12,1,72. 

N- 

#7. 

8:27,91,75. 

9:27,91,74. 

#10 ansi terminals do 

#11 not have these 

12:7. 

13:27,91,50,74. 

end of screen section 



version 
screen size 



DEBUGGER 



cursor left 

goto x y 
insert char 
delete char 

clear to eol 
clear to eos 
insert line 
delete line 
bell 
clear screen 



SIMULATOR 
cursor up 
cursor down 
cursor left 
cursor right 
goto x y 
insert char 
delete char 
clear to eol 
clear to eos 
insert line 
delete line 
bell 
clear screen 



keyboard section 

# 

# 

2:127, 

2:8. 

6:27,91,65. 

7:27,91,66. 

8:27,91,68. 

9:27,91,67. 

12:21. 

14:1. 

15:5. 

18:27,85. 

18:27,117. 

19:27,68. 

19:27,100. 

20:27,86. 

20:27,118. 

21:27,87. 

21:27,119. 

26:14. 



KEY 



DEBUGGER 



SIMULATOR 



# DELETE 


del char 




# BACKSPACE 


del char 




# UP 


cursor up 


cursor up 


# DOWN 


cursor down 


cursor down 


# LEFT 


cursor left 


cursor left 


# RIGHT 


cursor right 


cursor right 


# Crtl-U 


delete line 




# CTRL-A 


start of line 


start of line 


# CTRL-E 


end of line 


end of line 


# ESC U 


line up 




# ESC u 


line up 




# ESC D 


line down 




# ESC d 


line down 




# ESC V 


page up 


page up 


# ESC v 


page up 


page up 


# ESC W 


page down 


page down 


# ESC H 


page down 


page down 


# CTRL-N 


enter file 
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27:24. 


f 


CTRL-X 


exit file 




28:12. 


f 


CTRL-L 


refresh 


refresh 


28:23. 


# 


CTRL-W 


refresh 


refresh 


29:27,70. 


f 


ESC F 


change file 




29:27,102. 


f 


ESC f 


change file 




31:27,88. 


# 


ESC X 


finish 




34:27,72. 


# ESC H 


help 


help 


34:27,104. 


# ESC h 


help 


help 


36:27,65. 


# ESC A 


get address 




36:27,97. 


# 


ESC a 


get address 




39:7. 


f 


CTRL-G 


goto line 




40:27,43. 


# 


ESC 


backtrace 




41:27,49. 


1 


ESC 1 


inspect 




41:9. 


1 


CTRL-I 


inspect 




42:27,50. 


# 


ESC 2 


channel 




43:27,51. 


# ESC 3 


top 




44:27,52. 


# 


ESC 4 


retrace 




45:27,53. 


1 


ESC 5 


relocate 




46:27,54. 


f 


ESC 6 


info 




47:27,55. 


# 


ESC 7 


modify 




48:27,56. 


S 


ESC 8 


resume 




49:27,57. 


f 


ESC 9 


monitor 




50:11. 


1 


CTRL-K 


word left 




51:16. 


f 


CTRL-P 


word right 




55:27,60. 


1 


ESC < 


top of file 




55:27,62. 


| 


ESC > 


end of file 




62:27,116. 


# 


ESC t 


toggle hex 




62:27,84. 


v- 


ESC T 


toggle hex 




65:27,67. 


# 


ESC C 


continue from 




65:27,99. 


1 


ESC c 


continue from 




66:2. 


f 


CTRL-B 


toggle break 




67:6. 


# 


CTRL-F 


search (Find) 




end of keyboarc 


L section 









# idebug key that isn't really part of iterm but its here all the 
# 
# 

# INTERRUPT CTRL A — IDEBUG 



THAT'S ALL FOLKS 
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E.1 Introduction 

Special loading procedures can be created for the program and used in place of, 
or in addition to, the standard INMOS bootstrap. The file containing the new boot- 
strap is specified by invoking the collector with the 'B' and 'T' options. 

User defined bootstraps must perform all the necessary operations to initialize the 
transputer, load the network, and set up the software environment for the applica- 
tion program. 

Bootstraps are output to the program bootable file as the first section of code in 
the bootable file. The bootstrap, consisting of the primary and secondary bootstrap 
sequences, is followed by the standard INMOS network loader program, which is 
output in small packets, each packet consisting of a maximum of 60 bytes. The last 
packet of the network loader is followed by a length byte of zero. 

In most cases a custom bootstrap will interface directly with the standard INMOS 
Network Loader, which places various pieces of code and data within the trans- 
puter memory in a controlled way. However, it is possible to skip the standard 
loader by sinking its code packets and following the commands used by the 
network loader that are output after the network loader. 

The general format of a custom bootstrap is a concatenated sequence of bootstrap 
code segments each preceded by a length byte. The sequence can be any length. 
The bootstrap program must be contained in a single file. 

The source of the standard INMOS Network Loader is supplied with the toolset and 
is fully commented. See the accompanying Delivery Manual for details of source 
directories supplied. 



E.1.1 The example bootstrap 

The example bootstrap loader provided on the tootset examples directory is a 
combination of several files used in the standard INMOS bootstrap scheme. The 
files have been combined into a single file to illustrate how to create a user-defined 
bootstrap; the functionality is the same as that used in the the standard INMOS 
scheme based on multiple files. 

The program is written in transputer code and consists of two parts: 

• Primary bootstrap - performs processor setup operations such as initial- 
izing the transputer links 
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• Secondary bootstrap - sets up the software environment and interfaces to 
the Network Loader. 

Transfer of control 

The calling sequence in the standard INMOS scheme is as follows: 

The primary loader calls the secondary loader, which then calls the Network 
Loader When the Network Loader has completed Its work control returns to the 
secondary loader, which calls the application program via data set up by the 
Network Loader. 

Custom bootstraps should follow the same sequence. 

E.1.2 Writing bootstrap loaders 

Bootstrap loader programs should be written to perform the same operations as 
the standard scheme, that is, hardware initialization, setting up the software envi- 
ronment, and calling the Network Loader. If you skip the Network Loader by sinking 
its code bytes then you must ensure its function is reproduced in your own code. 
If you do use the Network Loader you must ensure the interface to it is correct by 
setting up the invocation stack. The method by which this is achieved can be 
deduced from the example program source. 

If you wish to make only a few small changes to the standard loader, for example, 
insert code to initialize some D-to-A converters, then the example code can be 
used and the required code can be inserted between the Primary and Secondary 
Loader code as an additional piece of bootstrap code in the sequence of boot- 
straps. The rest of the code can be used as it stands. 

If you decide to devise your own loading scheme and rewrite the Primary and 
Secondary Loaders then you should be familiar with the design of the Transputer 
and its instruction set. For engineering data about the transputer consult the 
' Transputer Databook ' and for information about how to use th e instruction set see 
the 'Transputer Instruction Set: a compiler writer's guide '. 
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Symbols 



!,idabug, 101, 104, 111,125 

::, idebug, 115 

# 
idebug, 85 
idump, 143 
isim, 274 

#alias, 188 

#C0MMENT 1 15 

#define, linker directive, 189 

#IMP0RT, 14 

# INCLUDE, 13 

finclude, linker directive, 189 

fmainentry, 189 

#OPTION, 16 

#PRAGMA, 17 
COMMENT, 18 
EXTERNAL, 18 
LINKAGE, 18, 190 
PERMITALIASES, 19 
SHARED, 19 
TRANSLATE, 14, 20 

tpragma, IMS_linkage, 190 

#reference, 189 

fsection, 190 

#USE, 14 

$ 

idebug, 85 
idump, 143 

% 
idebug, 85, 116 
imap, 241 
isim, 274 

@, iserver, 261 

+, idebug, 126 



++, idebug, 125 

*, idebug, 92, 116, 121,123,128 

" idebug, 123, 128 



Action strings, in makefiles, 235 

Alias check, 5, 16 
disable, 10, 19 

ALT, 9 

Analyse, 74, 82, 83, 85 

Array, subranges, 115, 125 
ASM, 16,34 
ASSERT, 9, 32 

B 

B0Q4, 285 

BOOS, 285 

| BACKTRACE] , 112 

binary. See output, format 

Binary lister, 205 
command line, 206 
errors, 219 

Binary output, ieprom, 170 

Block mode, ieprom, 171 

Boards, wiring, 74 

Boot from link, 145 
collector memory map, 61, 64 
default collector output, 52 

Boot from ROM, 52, 59, 145, 163 

configurer options, 30 
Bootable code, 27, 47 
bootable. file, 166 

Bootstrap 
alternatives, 60 
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example, 347 
loaders, 60, 348 



| BREAK | key, 255, 288 

Breakpoint, 90, 276 
commands, 90 
menu, 90 

Breakpoint debugging, methods, 75 

Building libraries, 179 

byte. select, 168 



Capability, 255, 259 
specific host, 261 

centry. lib, 15 

CHAN OF ANY, 9, 33 

| CHANGE FILE"] , 113 

Change processor, debugging, 103 



I CHANNEL L 110 



Checking, a network, 91 

Clearing, error flag, 133, 289 

Code 
allocation in memory, 34 
insertion, 16 
listing, 210 
position in memory, 32, 53, 55 

Collector 
command line, 48 
error messages, 67 
input files, 51 
output files, 51 
non-bootable, 58 

Command line, 293 

Command tine options 
icollect, 50 
idebug, 77 
iemit, 146 
ieprom, 165 
ilibr, 176 
ilink, 187 



ilist, 207 

imakef , 226 

imap, 241 

i server, 253 

isim, 272 

iskip, 286 

oc, 7 

occonf , 30 

specify transputer target, 308 

COMMENT pragma, 18 

Comments 
in EPROM control files, 165 
in object code, 15, 18 

Compare memory, debugging, 91 

Compatibility 
error modes, 8 
with previous toolsets, 32 

Compilation 
error modes, 8 
order of, 11 
targets, 7 

Compiler 
command line, 4 
command line options, 5, 7 
diagnostics, implementation data, 

299 
directives, 12 

syntax, 13 
error messages, 20 
file names, 7 
libraries, disabling, 6 
memory map, 11 
occam, 3 

selective loading of libraries, 1 78 
warning messages, 20 
warnings, enable/disable, 9 

Compiling, for a range of trans- 
puters, 302 

Configuration 
description, 27 
error modes, 31 
warning messages, enable/dis- 
able, 32 

Configurer, 27 
command line, 28 
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error messages, 35 
memory map, 34 
options, 29, 30 
search paths, 30 

Connection database, 260 
example, 263 
format, 262 



| CONTINUE FROM] , 111 

Conventions 
command line options, 293 
command line syntax t 293 
error messages, 299 
filenames, 294 
imakef file extensions, 298 
search paths, 294 
standard file extensions, 295 

Core dump, 74, 143, 279 
listing, 218 

Current location, in debugger, 112 

Cursor positioning, 341 



Data, listing all, 216 

Debug, support functions, 97, 111 

Debugger, 73 
command line, 75 
environment variables, 78 
errors, 133 
monitor commands 

definitions, 89-108 

editing functions, 86 

mapped by ITERM, 86 

summary, 86-88 
monitor page 

commands, 85 

scroll keys, 88 

symbolic commands, 88 
program hangs, 1 33 
scroll keys, 85 
symbolic functions, 108 

Debugging 
See also Monitor page 
B004 boards, 82 



current location, 112 

data, 5 

inspecting channels, 110 

inspecting memory, 125 

interactive, 196 

options, for different boards, 84 

program termination, 79 

single step, 280 

TRAMs, 82 

Default, memory map, 34 

DELETE, 228 

Directives, linker, 188 

Directory path, 294 

Disable 

alias checking, 19 

configurer warnings, 32 

error detection, 8 

interactive debugging, 16, 33 

range checks, 9, 16, 31 

run-time checks, 9, 16, 31 

separate vector space, 16 

usage checking, 16, 19 

virtual routing, 32 

warning messages, 9 

Disassemble memory, 92 

Display 
debugging messages, 105 
memory in hex, 95 
object code, 205 
processes, 105 
reference, 216 
run queues, 104 
timer queues, 105 

DRAMtimimg parameters, 155 

Dynamic code loading 
file format, 58 
listing files, 218 



Early write, 153 

Editing functions, 86 

Editing makefiles, 235 

EMI, 145 
clock period, 153 
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END OF FILE I, 89, 113 



end. offset, 168 



| ENTER FILEl , 113 

Entry point, 20 

Environment variables, 342 
accessing through iserver, 328 
IBOARDSIZE, 53 
ICOLLECTARG, 51 
ICONDB, 254, 261 
ILIBRARG, 176 
ILIHKARG, 187 
ILISTARG, 208 
ISESSION, 254 
ISIMBATCH, 281 
ITERM, 82 p 273 
TRANSPUTER, 254, 260 
used by idebug, 78 

EPROM, 30, 59 
code layout, 168 
devices, 172 

EPROM program converter, 163 
binary output, 170 
block mode, 171 
command line, 164 
control file, 165 
errors, 174 
hex dump, 170 

Intel extended hex format, 171 
Intel hex format, 171 
Motorola S-record format, 170 
output files, 170 

EPROM programming, 163 

eprom. space, 166 

Error 

detection, disable, 8, 31 
handling, 299 
modes, 8, 191 

behavior, 31 

compatibility, 8, 31 

configurer, 31 

HALT, 8 

selective loading of libraries, 178 

STOP, 8 

UNDEFINED, 9, 17, 31 



UNIVERSAL, 8 
runtime, 300 
severities, 299 

Error flag 
clearing in a network, 133, 289 
detection in interactive debugging, 
83 

Error messages 
format, 299 
icolloct, 67 
idebug, 133 
idurap, 144 
iemit, 159 
ieprom, 174 
ilibr, 182 
ilink, 199 
ilist, 219 
imakef , 235 
ixoap, 249 
iserver, 266 

additional, 268 
isim, 282 
iskip, 289 
oc, 20 
occonf , 35 
runtime memory initialization, 56 

Ethernet, 261 

Event, 99, 279 

Examples 
#COMMENT, 16 
# IMPORT, 15 
#OPTION, 17 
#PRAGMA EXTERNAL, 18 
#PRAGMA LINKAGE, 19 
#PRAGMA TRANSLATE, 20 
bootstrap loader, 347 
connection database, 263 
ieprom control file, 173 
imakef , 228 

mixed languages, 233 

Occam, 231 
oc, 5 

occonf, 28 

skipping a single processor, 287 
skipping multiple transputers, 287 

I EXIT FILE I, 113 
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Exported names, listing, 212 

Extensions 
file, 295 

required by imakef , 222, 298 
language, 3 

External memory interface, 145 

external pragma, 18 

External references, listing, 219 

extintel. See output . format 

Extraction of library modules, 192 



File 
extensions, 295 
imap source files t 241 
required by imakef, 222, 298 
identification, 217, 295 
name, conventions, 294 
types read by idebug, 77 

| FINISH | , 114 

Free memory, 35 
Function keys, idebug, 82 



| GET ADDRESS] , 113 
Go to process, 95 
| GOTO LINE""] , 113 
GUY, 9, 33 

H 

HALT error mode, 8, 31 

Heap area, 54 
position in memory, 53 



HELP 1,88,108, 113 



hex. See output . format 



Hexadecimal 
arguments to idump, 143 
listing, 212 

Hexadecimal format, for EPROM, 
170 

Host 
for capability, 261 
versions, xix 

Host file server, 251 
terminating, 288 

I 

IBOARDSIZE, 53, 79 
errors, 56 

icollect 
command line, 48 
command line options, 50 
environment variables, 51, 53 
errors, 67 

ICOLLECTARG, 51 

ICONDB, 254, 261 

idebug, 73 
command line, 75 

options, 77 
environment variables, 78 
errors, 133 
interactive mode, 81 
post-mortem debugging, 79 
restarting, 81 

IDEBUGSIZE, 79 
errors, 133 

idump, 74, 143, 255, 285 
errors, 144 

iemit, 145 
command line, 146 
DRAM timing parameters, 155 
errors, 159 
index page, 148 
input parameters, 150 
memory read cycle, 156 
memory write cycle, 157 
timing information, 154 

ieprom, 163 
command line, 164 
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control file, 165 
errors, 174 

if, 9 

ilibr, 175, 177 
command line, 176 
command line options, 176 
error messages, 182 

ILIBRARG, 176 

ilink,185 
command line, 186 
indirect files, 1 87 

ILIHKARG, 187 

ilist, 15, 205 
command line, 206 
command line options, 207 
errors, 219 

ILISTARG, 208 

imakef , 3, 7, 13, 198,221 
command line, 225 
command line options, 226 
deleting intermediate files, 228 
errors, 235 
examples, 228 
file extensions, 222, 298 
Hie formats, 234 
linker indirect files, 225, 227 
mixed language example, 233 
occam examples, 231 
target files, 222 

imap, 239 
command line, 240 
command line options, 241 
errors, 249 
output file structure, 243 

Implementation, compiler diagnos- 
tics, 299 

IMS B004, 285 

IMS B008, 285 

IMS B404, 83 



I INSPECT | , 109 

Inspect memory, 96 

intel. See output. format 

Intel extended hex format, ieprom, 
170 

Intel hex format, ieprom, 170 

Interactive debugging 
collector option, 66 
compiler support, 10 
configurer option, 33 
detecting the error flag, 83 
disabling, 33 
invocation, 81 
methods, 75 



INTERRUPT I, 111 



INFO j, 110 



INQUEST, xxi, 34 



ISEARCH, 30, 294 
i server, 251,285 

accessing transputers, 260 

capability, 255 

command line, 252 

command line options, 252 

connection manager, 265 

environment variables, 254 

error codes, 266 

error messages, 266 

exit codes, 266 

functions, 251 

halt system error mode, 255 

loading programs, 254 

new features, 265 

passing parameters to a program, 
255 

protocol, 309 
ALSYS-Alsys call, 335 
CommandArgs - get command 

line arguments, 333 
CommandLine - get server 

command line, 329 
Core - read peeked memory, 

330 
Exit - exit the server, 329 
Fciose - close a file, 312 
Feof- test for end of file, 321 
Ferror - get file error status, 322 
FerrStat - Get file error status, 
324 
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Fflush -flush a stream, 316 
FGetBlock - read and return 

success, 314 
FGetRec - read a record, 319 
Fgets - read a line, 315 
file commands, 311 
FileExists, 324 
Fopen - open a file, 311 
FopenRec - open record file, 

317 
FPutBlock - write and return 

success, 315 
FPutEOF - write end-of-file, 320 
FPutRec - write a record, 319 
Fputs- write a line, 316 
Fread - read block of data, 313 
Fseek - set position in a file, 

320 
Ftell - find position in a file, 321 
Fwrite - write block of data, 313 
Getenv - get host variable, 326 
Getlnfo - get host and server 

info, 332 
Getkey - get keystroke, 325 
host commands, 325 
Isatty - terminal connect status, 

323 
KPAR - Kpar call, 336 
MSDOS - MS-DOS command, 

334 
packets, 309 

Pollkey - test for key press, 325 
record structured file 

commands, 317 
record structured file format, 336 
Remove - delete a file, 322 
Rename - Rename a file, 323 
Requestkey - request keyboard 

event, 326 
reserved commands, 334 
server commands, 329 
SocketA - socket library call, 

335 
SocketM - socket library call, 

335 
System - run a command, 327 
termination codes, 337 
Time - get the time of day, 327 



Translate - translate an environ- 
ment variable, 328 

Version - server info, 331 
record structured files, 266 
session manager, 252, 256, 265 

customizing interface, 258 
specifying the transputer to use, 

255 
stream identifier validation, 266 
subsystem reset, 264 
terminating, 255 

on error, 255 
user interrupt, 265 

ISESSION, 254, 256 

isim, 271 
command line, 271 
command line options, 272 
errors, 282 

ISIMBATCH, 281 

iskip, 74, 285 
command line, 286 
command line options, 286 
errors, 289 

ispy, 133,289 

ITERM, 79, 82, 273, 342 

ITERM file 
example listing, 344 
format, 339 
keyboard, 342 
screen, 340 

use by simulator, 273, 274 
version, 340 



JEDEC, symbol, 154,156 
Jump instructions, in ROM, 169 
Jump into program, 97 
Jumping down a channel, 110 

K 

Keyboard, definitions, 342 
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Late write, 153 

LFF files, listing, 218 

libc,lib,15 

Librarian, 175 
command line, 176 
concatenated input, 175 
linked object input, 177 
options, 176 

Library 
building, 179 
building optimized, 179 
compilation, 10 
extraction of modules, 1 92 
index, 175, 178 
indirect files, 175, 177 

imakef , 225 
linking supplied libraries, 188 
listing index, 214 
modules, 177 
selective loading of, 178 
usage files, 178 

iinakef , 225 



LINE DOWN I, 89 



I LINE UP I, 88 



Link 
debugging, 99 
debugging simulated, 279 
map, 197 

linkage pragma, 18 

Linker, 185 
command line, 186 
compatible transputer classes, 

190 
directives, 188 
errors, 199 

extraction of library modules, 192 
indirect files, 187 

imakef , 225, 227 
LFF output, 191 

selective loading of libraries, 178 
TCOFF output, 191 



Linking, transputer targets, 301 

Lister. See ilist 

Loading programs 
iserver, 251 
iskip. 288 

LoadStart, 34, 35,61,63 

localhost, 261 
Location, in debugger, 112 
location . code, 32 
location, vs, 32 
location. vs, 32 
Logical name, 342 

M 

Macros, in makefiles, 234 

Main entry point, 195 

Make programs, 221 
Borland, 221 
Gnu, 221 
Microsoft, 221 
UNIX, 221 

Makefile generator, 221 
command line, 225 
errors, 235 

Makefiles 
delete rule, 235 
editing, 235 
formats, 234 
macros, 234 

MemConflg, 145 

MemnotWrDC, 145 

Memory 
configuration 
ASCII output, 148 
customized, 145 
file, 160 
in PAL, 145 
in ROM, 145, 168 
PostScript output, 148 
standard, 145, 153 
table, 158 
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configurer, 145 

command line, 146 

default configuration, 148 

errors, 159 

input parameters, 150 

interactive operation, 148 

output files, 148 
disassembly, 276 
Hex display, 95 
inspecting, 278 
interface, configurable, T4 and T8 

series, 145 
mapper, 239 

command line, 240 

errors, 249 
on-chip, 18, 35 
parity-checked, 57 
read cycle, 1 56 
write cycle, 157 

Memory dumper, 143 
command line, 143 
error messageSj 144 

Memory map, 100, 279 
boot from link (network), 64 
boot from link (single processor), 

61 
boot from ROM, 65 
collector output, 60 
configurer, 34 

memory, configuration, 166 

MemStart, 35, 61 

MemWait, 153, 157 
connection error, 159 

Mixed language programming 
#IMP0RT directive, 14 
translate pragma, 20 
use of imakef , 233 



MODIFY I, 111 



Module data, listing, 213 

| MONITOR | , 114 

Monitor page 
See also Debugging 
commands, 85 
default address, 85 



display virtual links, 107 
Enter post-mortem, 106 
exit, 106 
simulator, 273 

Monitoring the error status, 288 

MOSTNEG INT, 85 

Motorola S-record format, ieprom, 
171 



MS-DOS, 293 

N 



Network, dump, 101 
listing, 218 

Next error, 93 

Non-bootable files, format, 58 

Non-configured programs. See 
icollect 

notMemRd, 152 

notMemSO, 152 

notMemS4, 152 

notMemWrB, 152 

Numerical parameters, Interpreta- 
tion byisim, 274 



Object code, displaying, 205 

Object file, 4 

oc r 3 
command line options, 7 
error messages, 23 
memory map, 11 
syntax, 4 
warning messages, 20 

occam, interface code i 52 

occonf , 27 
command line options, 29, 30 
error messages, 35 
syntax, 28 
warning messages, 36 

On-chip RAM, 18,35 
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Optimization, code placement, 18 

Options 
in Occam source, 16 
specify transputer target, 308 
standard, 293 
unsupported, 294 

order . coda, 32 

order, vs, 32 

order, ws, 32 

Out of memory errors, idebug, 133 

output, address, 168 

output, all, 167 

output. block, 167 

output . format, 1 67 



PAGEDOWN"], 89 



| PAGE UP | , 89 
PAR, 9 

Path searching, 294 

PERMITALIASES pragma, 19 

Port, 22 

Post-mortem debugging 
dummy network, 75 
from core dump, 75 
invocation, 79 
R-mode programs, 74 
T-mode programs, 74 

Pragmas. See #pragma 

Priority, 104 

ProcClockOut, 152,153 

Procedural interface data, listing, 
215 

Process 
memory map, 105 
queue, 280 
displaying, 104 



Processor 
names, 99 
types, 301 

Protocol, iserver, 309 



Queue 
process, 1 04, 280 
run, 104, 280 
timer, 280 

Quit 
debugger, 104 
simulator, 279 



R-mode programs, 74 

RAM, 18,30, 59,65 

Read, strobe, 152 

| REFRESH | , 88, 108 

Refresh period, 152 

Registers 
assigning value, 280 
memory dump, 144 



RELOCATE |, 88, 107, 112 



reserved, 35 

Reset, 82 

Resource, 255 

| RESUME | , 88, 108, 111 

Resume program 
from debugger, 98 
from simulator 278 



RETRACE 1,88,107,112 



Retry - server, 255 

ROM, 30, 59, 65, 163 

Root transputer 
debugging, 73 
loading over, 285 

root. processor. type, 166 
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Run queues, displaying, 104, 280 



Scalar workspace, 59 

Scheduling lists. See Process 
queue; Run queue 

Screen definitions, 340 

Screen size, 340 



| SEARCH] , 113 

Search path 
configurer, 30 
conventions, 294 

Select process, 102 

Select source file, 93 

Selective linking, 196 

Selective loading, libraries, 178 

Separate compilation, 10 

Separate vector space, 6 h 16 

SEQ r 9 

Session manager, 252, 256 
configuration file, 254 

shared pragma, 19 

Show debugging messages, 105 

Simulator, 271 
batch command files, 281 
batch commands, 281 
batch mode, 281 
booting program, 279 
command 

definitions, 275-281 

summary, 275 
command line, 271 
commands, 274 
errors, 282 
options, 272 
starting a program, 277 

SKIP, 32 

Skip loader, 285 
command line, 286 



command line options, 286 
errors, 289 

srecord. See output, format 

Stack, position in memory, 53 

stack. buffer, 56 

Standard memory configuration, 
153 

Standards 
command options, 293 
command syntax, 293 
file extensions, 295 

start. offset, 168 

Static area, position in memory, 53 

Static data, 54 

Static variables, memory map, 239 

STOP error mode, 8, 31 

Subsystem 
connecting, 82 
reset, 286 
wiring, 287 

Symbol data, listing, 209 

Symbolic debugging, 108 



T-mode programs, 74 

T4 series, configurable memory 
interface, 145 

T8 series, configurable memory 
interface, 145 

Target files, for imakef , 222 

Target transputer, 301 
command line options, 308 

TCOFF, 4 
listing files, 218 

Terminate 
on error, 255 
the server, 255 

Text files, listing, 218 

Timer queue, displaying, 105, 280 
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Timing data, 154 

Tm, 152 

| TOGGLE BREAK] , 111 



| TOGGLE HEX |, 114 

Toolset 
documentation, xx 
conventions, xxi 
standards and conventions, 293 

[W], 88, 107, 112 
| TOPOFFII_E~| . 89, 113 

Traceback information, in ROM, 
170 

TRAM, 285 

TRANSLATE pragma, 14 

TRANSPUTER, 254, 255, 260 

Transputer 
accessing, 252 

on a remote host, 261 

on the local host, 261 
classes, 7 
simulator, 271 
targets, 4, 7, 301 

command line options, 308 

u 

UNDEFINED error mode, 9, 17, 31 

UNIVERSAL error mode, 8, 31 

UNIX, 293 

Unresolved references, 196 

Unsupported options, 294 

Update registers, 105 

Usage check, 6, 1 6 
disable, 19 

User link, 252, 259 



position in memory, 55 
Virtual memory, 195 
Virtual routing, disabling, 10, 32 
VMS, 293, 342 

w 

Wait 
connection, 153 
race, 153 

error, 159 
states, 153 

Warnings. See Error messages 

Waveform diagrams, 156 

Wired down, 82, 287 

Wired subs, 82, 287 

Workspace, 18 
default, 34 

Write 
mode, 153 
strobe, 152 
to memory, in idebug, 106 



Vector space, 18, 59 
default, 34 



z, command line option, 294 
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